Mermaid vs PlantUML C4 图对比：架构视图、语法差异与选型

本文只关注 C4 架构图本身的图形表达能力。 至于 Markdown 支持、文档平台集成、生态插件、渲染服务这些整体工具差异，本文不会展开，相关内容可以看系列总览：Mermaid vs PlantUML：2026 年该选哪个图表即代码工具？。

在这个前提下，结论需要稍微谨慎一点：Mermaid 官方提供了 C4 Diagram 语法，但目前仍标记为 experimental，适合轻量架构说明和快速嵌入文档；PlantUML 通常通过 C4-PlantUML 库来画 C4 图，能力更成熟，更适合架构评审、统一样式、复杂布局和长期维护。

这里有一个很容易写错的边界：C4-PlantUML 不是 PlantUML 核心 UML 语法里的一个普通图类型，而是基于 PlantUML 的 C4 宏库。它可以通过 PlantUML 标准库 !include <C4/C4_Container> 使用，也可以直接引用 C4-PlantUML 仓库里的最新文件。也就是说，比较 C4 时，更准确的说法是：Mermaid C4 Diagram vs C4-PlantUML。

更准确的判断是：

Mermaid 胜在轻量直接。 它的 C4 语法和 C4-PlantUML 很接近，支持 System Context、Container、Component、Dynamic、Deployment 五类 C4 图。对于在 Markdown 文档里快速画一张上下文图或容器图，Mermaid 的门槛更低。

C4-PlantUML 胜在完整生态。 它有更成熟的 include 体系、布局辅助、tag/stereotype、主题、图例、sprite、样式和大量样例，更适合团队把 C4 图作为稳定的架构文档资产维护。

本文基于官方文档整理，并配合具体案例对比代码和图形效果：

Mermaid vs C4-PlantUML 核心差异

对比点	Mermaid C4	C4-PlantUML	选择建议
定位	Mermaid 内置的 experimental C4 图	PlantUML 上的 C4 宏库/标准库	正式架构资产 C4-PlantUML 更稳
Context 图	支持 `C4Context`	支持 `C4_Context.puml` / `<C4/C4_Context>`	两者都可以
Container 图	支持 `C4Container`	支持 `C4_Container.puml` / `<C4/C4_Container>`	两者都可以
Component 图	支持 `C4Component`	支持 `C4_Component.puml` / `<C4/C4_Component>`	两者都可以
Dynamic 图	支持 `C4Dynamic`	支持 `C4_Dynamic.puml` / `<C4/C4_Dynamic>`	C4-PlantUML 更成熟
Deployment 图	支持 `C4Deployment`	支持 `C4_Deployment.puml` / `<C4/C4_Deployment>`	C4-PlantUML 更成熟
语法兼容性	设计上兼容 C4-PlantUML 的一部分语法	原始 C4-PlantUML 宏能力更完整	复杂图优先 C4-PlantUML
布局控制	主要靠声明顺序和 `UpdateLayoutConfig`	支持更多布局辅助和方向控制	复杂布局 C4-PlantUML 更合适
标签和图例	官方文档列出 tags、link、Legend 等短期不支持项	支持 tag、stereotype、legend、theme 等	架构规范图选 C4-PlantUML
样式控制	固定风格为主，支持有限 style update	支持主题、skinparam、tag 样式、sprite 等	统一视觉规范选 C4-PlantUML
文档嵌入	很方便	取决于 PlantUML 渲染集成	README/轻量文档 Mermaid 更轻

先给一句话结论：

Mermaid C4 适合快速说明架构视图；C4-PlantUML 适合把 C4 模型当成团队长期维护的架构语言。

Mermaid 也能快速画 C4 Context 图

C4 Context 图关注系统边界：谁使用这个系统，它和哪些外部系统交互。对这种图来说，Mermaid 的 C4 语法已经可以表达核心元素：Person、System、System_Ext 和 Rel。

Mermaid 代码和图

C4Context
  title System Context diagram for OnUML

  Person(user, "Diagram Author", "Creates and edits architecture diagrams")
  System(onuml, "OnUML", "Diagram-as-code editor for Mermaid and PlantUML")
  System_Ext(github, "GitHub", "Stores documentation and source code")
  System_Ext(email, "Email Service", "Sends workspace notifications")

  Rel(user, onuml, "Creates diagrams with")
  Rel(onuml, github, "Exports documentation to")
  Rel(onuml, email, "Sends notifications through")

C4-PlantUML 代码和图

@startuml
!include <C4/C4_Context>

title System Context diagram for OnUML

Person(user, "Diagram Author", "Creates and edits architecture diagrams")
System(onuml, "OnUML", "Diagram-as-code editor for Mermaid and PlantUML")
System_Ext(github, "GitHub", "Stores documentation and source code")
System_Ext(email, "Email Service", "Sends workspace notifications")

Rel(user, onuml, "Creates diagrams with")
Rel(onuml, github, "Exports documentation to")
Rel(onuml, email, "Sends notifications through")
@enduml

对简单 Context 图来说，两者差异并不大。Mermaid 的优势是少了 include 和 PlantUML 包裹语法，更适合快速贴进文档；C4-PlantUML 的优势是后续可以自然接入更完整的 C4 生态能力。

Container 图两者都能表达核心架构

Container 图关注系统内部由哪些可部署或可运行单元组成，比如 Web App、API、Database、Queue。下面是一个简化的 OnUML 容器视图。

Mermaid 代码和图

C4Container
  title Container diagram for OnUML

  Person(user, "Diagram Author", "Creates architecture diagrams")

  System_Boundary(onuml, "OnUML") {
    Container(web, "Web App", "Next.js", "Provides editor and documentation UI")
    Container(api, "API Routes", "Next.js Edge Runtime", "Handles rendering and workspace requests")
    ContainerDb(db, "Database", "PostgreSQL", "Stores users, projects, and workspaces")
    ContainerQueue(queue, "Job Queue", "Queue", "Processes async rendering jobs")
  }

  System_Ext(email, "Email Service", "Sends notifications")

  Rel(user, web, "Uses")
  Rel(web, api, "Calls", "HTTPS")
  Rel(api, db, "Reads and writes")
  Rel(api, queue, "Publishes jobs")
  Rel(api, email, "Sends email through")

C4-PlantUML 代码和图

@startuml
!include <C4/C4_Container>

title Container diagram for OnUML

Person(user, "Diagram Author", "Creates architecture diagrams")

System_Boundary(onuml, "OnUML") {
  Container(web, "Web App", "Next.js", "Provides editor and documentation UI")
  Container(api, "API Routes", "Next.js Edge Runtime", "Handles rendering and workspace requests")
  ContainerDb(db, "Database", "PostgreSQL", "Stores users, projects, and workspaces")
  ContainerQueue(queue, "Job Queue", "Queue", "Processes async rendering jobs")
}

System_Ext(email, "Email Service", "Sends notifications")

Rel(user, web, "Uses")
Rel(web, api, "Calls", "HTTPS")
Rel(api, db, "Reads and writes")
Rel(api, queue, "Publishes jobs")
Rel(api, email, "Sends email through")
@enduml

如果只是表达 Person、System、Container、Database、Queue 和关系，两者都能完成。C4-PlantUML 的价值会在图越来越多、需要统一样式和布局规则时变得明显。

C4-PlantUML 更适合复杂架构图规范

Mermaid 官方 C4 文档明确提示 C4 Diagram 仍是 experimental，语法和属性未来可能变化；同时也说明 Mermaid C4 的样式较固定，布局主要受声明顺序影响，并且 tags、link、Legend 等能力没有完整支持。

C4-PlantUML 则更适合做团队级规范图。它不仅有 Context、Container、Component、Dynamic、Deployment 等 C4 图，还提供：

LAYOUT_* 和 Lay_* 等布局辅助。
tag/stereotype，用于区分风险、外部系统、遗留系统、云服务等。
theme、skinparam 和样式扩展，用于统一团队输出。
legend，用于解释颜色、线型和标记。
sprite 和图标，用于表达云厂商、技术组件或自定义资产。

下面是一个更偏评审场景的 C4-PlantUML 示例：给遗留系统加 tag，并输出图例。

C4-PlantUML 代码和图

@startuml
!include <C4/C4_Container>

AddElementTag("legacy", $bgColor="#fff3cd", $borderColor="#b7791f", $legendText="Legacy system")
AddRelTag("async", $lineStyle=DashedLine(), $legendText="Async message")

title Container diagram with architecture review tags

Person(user, "Diagram Author")

System_Boundary(onuml, "OnUML") {
  Container(web, "Web App", "Next.js", "Editor and documentation UI")
  Container(api, "API Routes", "Next.js Edge Runtime", "Workspace and rendering API")
  ContainerQueue(queue, "Job Queue", "Queue", "Async rendering jobs")
}

System_Ext(oldRenderer, "Legacy Renderer", "Old rendering service", $tags="legacy")

Rel(user, web, "Uses")
Rel(web, api, "Calls")
Rel(api, queue, "Publishes job", $tags="async")
Rel(api, oldRenderer, "Falls back to")

SHOW_LEGEND()
@enduml

Mermaid 近似表达

C4Container
  title Container diagram with architecture review notes

  Person(user, "Diagram Author")

  System_Boundary(onuml, "OnUML") {
    Container(web, "Web App", "Next.js", "Editor and documentation UI")
    Container(api, "API Routes", "Next.js Edge Runtime", "Workspace and rendering API")
    ContainerQueue(queue, "Job Queue", "Queue", "Async rendering jobs")
  }

  System_Ext(oldRenderer, "Legacy Renderer", "Old rendering service")

  Rel(user, web, "Uses")
  Rel(web, api, "Calls")
  Rel(api, queue, "Publishes job")
  Rel(api, oldRenderer, "Falls back to")

为什么这个场景更适合 C4-PlantUML？

Mermaid 可以表达这张图的主体结构，但不适合承载完整架构规范：

Mermaid C4 仍是 experimental，长期语法稳定性不如 C4-PlantUML。
Mermaid C4 的布局控制较有限，复杂图更容易依赖声明顺序。
Mermaid 官方文档明确列出 tags、link、Legend 等未完整支持项。
C4-PlantUML 可以用 tag、theme、legend、sprite 和布局辅助把图做成团队标准。

这就是 C4-PlantUML 在 C4 图里的真正优势：它不是只能多画几个元素，而是更适合维护一套架构表达规范。

C4 图选择建议

选 Mermaid 写 C4 图，如果这张图的重点是：

快速说明系统上下文或容器关系。
放在 README、Markdown 文档、轻量设计说明里。
图主要使用 Person、System、Container、Database、Queue 和 Rel。
不需要复杂布局、标签、图例、主题或统一视觉规范。
可以接受 Mermaid C4 当前 experimental 的状态。

选 C4-PlantUML 写 C4 图，如果这张图的重点是：

构建团队长期维护的架构图体系。
需要 Context、Container、Component、Dynamic、Deployment 多层视图。
需要布局控制、tag/stereotype、legend、theme、sprite 或样式规范。
需要把 C4 图放进架构评审、ADR、设计归档或技术治理流程。
需要更成熟的 C4 生态和大量可参考样例。

常见问题

Mermaid C4 是稳定语法吗？

不是完全稳定。Mermaid 官方文档明确标记 C4 Diagram 目前是 experimental，语法和属性未来可能变化。轻量文档可以使用，但长期架构资产要谨慎。

PlantUML 原生支持 C4 吗？

更准确地说，PlantUML 通过 C4-PlantUML 库支持 C4。你可以引用远程 C4-PlantUML 文件，也可以使用 PlantUML 标准库里的 <C4/C4_Container>、<C4/C4_Context> 等 include。

Mermaid C4 和 C4-PlantUML 语法兼容吗？

Mermaid 官方文档说明它的 C4 语法兼容 C4-PlantUML 的一部分，并建议参考 C4-PlantUML 语法。但这种兼容不是完整等价，Mermaid C4 仍有 tags、link、Legend 和部分样式能力限制。

只看图形能力，C4 图怎么选？

如果你只是想快速画一张 Context 或 Container 图，Mermaid 很方便。如果你要维护一套完整架构图，包括多层视图、样式规范、标签、图例和布局控制，C4-PlantUML 更合适。

最终结论：

C4 图这一项上，Mermaid 的优势是轻量、易嵌入、上手快；C4-PlantUML 的优势是成熟、完整、适合团队规范化维护。快速说明选 Mermaid，正式架构文档选 C4-PlantUML。

你可以在 OnUML 编辑器中分别使用 Mermaid 和 PlantUML 模式，把上面的示例复制进去对比效果。