OnUML LogoOnUML

Mermaid C4 vs C4-PlantUML：正式 C4 架构图选型

··Updated ·10 min read
mermaidplantumlc4-modelc4-diagramsoftware-architecturediagram-as-code

C4-PlantUML 明显优于 Mermaid C4，应当优先选择。 截至 2026-07-22，Mermaid C4 官方文档仍将该语法标记为 experimental，并明确提示语法和属性可能在后续版本中变化。因此，本文不建议正式项目把 Mermaid C4 作为默认方案。

本文只比较 C4 架构图本身。两种工具的整体差异请看 Mermaid vs PlantUML 系列总览；组件图、部署拓扑和服务关系的选择，则可以参考软件架构图专项对比。

本文引用的官方资料统一核验于 2026-07-22。

先明确比较对象：C4-PlantUML 不是 PlantUML 核心语法中的普通图类型，而是构建在 PlantUML 之上的 C4 宏库。C4-PlantUML 官方说明提供远程文件与标准库两种引用方式，因此本文准确比较的是 Mermaid C4 Diagram 与 C4-PlantUML。

核心结论

  • Mermaid C4 虽支持 5 类图，但仍处于 experimental 阶段。
  • Mermaid 官方列出的短期缺口包括 sprite、tags、link 和 Legend。
  • C4-PlantUML 以 include 与宏组织图，提供布局辅助、tag/stereotype、图例、sprite 和跨图样式复用，应作为正式 C4 文档的默认选择。

判断 C4 工具不能只看能否生成一张图，还要看一组图能否共享语义、样式和维护规则。本文将“基础元素表达”和“团队规范治理”分开比较，避免用一张简单示例掩盖长期维护差异。

Mermaid C4 与 C4-PlantUML 有哪些核心差异？

Mermaid C4 文档列出 System Context、Container、Component、Dynamic、Deployment 共 5 类图，同时说明样式固定、布局并非完全自动，并把 4 项能力列为短期不支持。相比之下，C4-PlantUML提供更完整的宏、布局与样式体系。

对比点Mermaid C4C4-PlantUML选择建议
定位Mermaid 内置的 experimental C4 图PlantUML 上的 C4 宏库/标准库正式架构资产 C4-PlantUML 更稳
Context 图支持 C4Context支持 C4_Context.puml / <C4/C4_Context>正式使用选 C4-PlantUML
Container 图支持 C4Container支持 C4_Container.puml / <C4/C4_Container>正式使用选 C4-PlantUML
Component 图支持 C4Component支持 C4_Component.puml / <C4/C4_Component>正式使用选 C4-PlantUML
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

版本与语义边界

Mermaid C4 的 5 类图是当前实现类型，不等同于 C4 Model 的 4 个核心静态层级。Dynamic 和 Deployment 是支持性视图；前者说明既有模型元素在用例中的协作，后者说明指定环境中的部署，两者都不应被误写成第五个核心静态层级。

Mermaid C4 能画 Context 图吗？

C4 Model 官方说明把 Context、Container、Component、Code 定义为 4 个核心静态层级，并指出多数团队使用 Context 与 Container 已经足够。Mermaid 的 C4Context 可以表达 Person、System、System_Ext 和 Rel，因此基础 Context 图并不是它的短板。

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

两段代码都能表达相同的系统边界。这个示例验证的是 Person、System 和 Rel 等基础元素，不涉及标签、图例或跨图复用，因此不能用于判断完整规范能力。

Container 图的差距体现在哪里？

Container 图描述系统内部可独立部署或运行的单元。C4-PlantUML 官方入门文档列出 Person、System、Container、Boundary 和 Relationship 等宏；Mermaid 也覆盖相应的 Container、Database、Queue 与关系元素。基础语义接近，规范能力不同。

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

这组示例验证了两种语法都能描述容器边界和依赖关系。方向、间距、颜色、标签与图例等跨图规则，需要在后面的规范场景中单独比较。

为什么 C4-PlantUML 更适合架构规范？

Mermaid 官方文档明确列出 4 个短期不支持项：sprite、tags、link、Legend；布局主要依赖声明顺序和 UpdateLayoutConfig，Lay_U、Lay_D、Lay_L、Lay_R 等方向语句在核验日也不在支持计划中。对需要评审标记和统一图例的团队来说，这些不是装饰性差异。

C4-PlantUML 官方仓库则直接提供布局选项、sprite、标签、stereotype、图例、主题和样式更新。它不仅覆盖 Context、Container、Component、Dynamic、Deployment，还能把下面这些约束写进图表代码：

  • !include <C4/C4_Container> 等标准库 include 与 Context、Container、Component、Dynamic、Deployment 宏。
  • LAYOUT_*、Lay_*、Lay_Distance 与图例布局辅助，便于调整复杂图的方向和间距。
  • AddElementTag、AddRelTag、$tags 与 stereotype，用于区分风险、外部系统、遗留系统、云服务等。
  • SHOW_LEGEND()、theme、skinparam、UpdateElementStyle() 和 sprite，可把说明与样式配置抽到独立文件供跨图复用。

下面的评审示例给遗留系统添加 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，存在后续语法和属性变化风险。
  • Mermaid C4 的布局控制较有限，复杂图更容易依赖声明顺序。
  • Mermaid 官方文档明确列出 tags、link、Legend 等未完整支持项。
  • C4-PlantUML 可以用 tag、theme、legend、sprite 和布局辅助把图做成团队标准。

C4-PlantUML 的优势不是多画几个元素，而是把“遗留系统是什么颜色”“异步关系用什么线型”“图例如何生成”变成可复用规则。图的数量增加后，这类规则比单张图的语法长度更重要。

C4 图到底应该选谁？

直接选 C4-PlantUML。Mermaid C4 虽然覆盖 5 类图，但 experimental 状态、固定样式和明确的功能缺口，使它不适合成为正式架构文档的基础。!include <C4/C4_Container> 已包含在 PlantUML Standard Library 的 C4 库中，不需要把远程依赖作为唯一使用方式。

以下需求都会进一步放大 C4-PlantUML 的优势：

  • 构建团队长期维护的架构图体系。
  • 需要 Context、Container、Component、Dynamic、Deployment 多层视图。
  • 需要布局控制、tag/stereotype、legend、theme、sprite 或样式规范。
  • 需要把 C4 图放进架构评审、ADR、设计归档或技术治理流程。
  • 需要使用 C4-PlantUML 官方样例作为团队模板。

选型底线很简单：如果图会进入评审、ADR、设计归档或治理流程，就不要把 experimental 语法作为基线。Mermaid C4 可以用于验证语法和渲染效果，但不应成为团队默认格式。

团队规范的最小基线

团队应把 C4-PlantUML 的 include、标签命名、关系样式和图例规则放进可复用配置，而不是逐图复制。工具不会自动验证标签含义，但统一宏与样式文件能让评审把注意力放在架构变化，而不是重新解释每张图的颜色和线型。

关于 Mermaid C4 与 C4-PlantUML 的常见问题

下面 5 个问题集中处理最容易混淆的边界：Mermaid C4 是否稳定、PlantUML 是否原生包含 C4、Dynamic 与时序图如何分工、两种语法是否等价，以及最终应该选择哪一个。答案均以 Mermaid、PlantUML 和 C4-PlantUML 官方资料为准。

Mermaid C4 是稳定语法吗？

不是。Mermaid C4 官方文档明确标记该图类型为 experimental，并说明语法和属性可能在未来版本中变化。只要官方仍保留这个警告，就不应把 Mermaid C4 视为稳定的团队架构基线。

PlantUML 原生支持 C4 吗？

不是核心 UML 语法原生图类型。PlantUML 通过 C4-PlantUML 宏库支持 C4；该库的发布版本已进入 PlantUML 标准库，可以用 <C4/C4_Container>、<C4/C4_Context> 等 include，也可以引用 C4-PlantUML 仓库中的最新文件。

C4 Dynamic 与时序图如何分工？

不应把两者当成同一张图的替代品。C4 Dynamic 用编号说明既有系统、容器或组件在某个用例中的运行时协作；需要表达消息级顺序、返回语义或调用栈时，应使用 Mermaid vs PlantUML 时序图。

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

只兼容一部分。Mermaid 文档建议参考 C4-PlantUML 语法，但同时列出了 tags、link、Legend、sprite 和自定义 stereotype 等缺口。相似的宏名称可以降低阅读成本，却不能证明功能完整等价。

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

C4-PlantUML 更好。它覆盖完整的多层视图，并提供布局、标签、图例、主题、sprite 与样式复用；Mermaid C4 仍有 experimental 警告和官方列明的功能缺口。正式架构文档应直接选择 C4-PlantUML。

正式 C4 文档应从 C4-PlantUML 开始；需要服务、组件与部署视图的总体边界，可回看软件架构图专项对比。