Mermaid vs PlantUML：日常文档与复杂架构如何选？
日常文档默认 Mermaid；正式 UML 与复杂架构图默认 PlantUML；需要覆盖多种图型的团队应同时保留两者。
官方资料核验于 2026-07-22。这里的“正式 UML”指需要稳定表达结构、交互或架构决策的设计文档，并不声称任一工具会自动验证 UML 标准符合性。本项目当前锁定 Mermaid 11.6.0；官网核验时的最新发布版本为 11.16.0，因此官网新增能力不应直接视为当前编辑器已经具备的能力。
核心结论
- README、PR、Wiki 和短生命周期说明图，先选 Mermaid。
- 类图、组件图、部署图、复杂交互与需要专用控制语法的设计文档，先选 PlantUML。
- 应用数据库 schema 默认看 Mermaid ER 图；需要 Chen 概念建模时看 PlantUML。
- C4 图、泳道图与官网新版本能力都有明确版本或功能边界，先确认渲染环境，再选语法。
本页是 Mermaid vs PlantUML 系列的入口。它给出团队级选型框架和阅读顺序，不展开各专项的具体语法。
30 秒内怎么按交付物选择？
先问图要完成什么交付，而不是先比较两套语法谁更短。需要和代码一起快速更新、读者主要在 Markdown 文档中查看时，Mermaid 是合适默认值。图要进入架构评审、跨团队接口说明或长期设计归档，且需要更细的声明元素、专用图类型或视图控制时，PlantUML 更适合作为默认值。
| 交付物 | 默认选择 | 选择理由 |
|---|---|---|
| README、PR 说明、Wiki 流程 | Mermaid | 用短文本维护日常沟通图，修改门槛低。 |
| 一次性服务关系或资源总览 | Mermaid | 适合快速展示服务与资源关系。 |
| 类、组件、部署等结构设计文档 | PlantUML | 有对应的声明元素和专用图语法。 |
| 复杂业务控制、跨角色流程 | PlantUML | 专用活动图控制结构和泳道表达更直接。 |
| 应用 schema ERD | Mermaid | Crow's Foot 与 PK、FK、UK 属性标记适合常见数据表关系。 |
| 概念数据模型或 C4 架构基线 | PlantUML | Chen 模式与 C4-PlantUML 提供了不同的专用表达范围。 |
能力矩阵：覆盖范围与边界
两种工具都以文本描述图表，但文本化不等于能力范围相同。Mermaid 的官方语法目录覆盖流程、时序、类、状态、ER 等常见图；PlantUML 的官方文档则分别提供类图、组件图、部署图、活动图和时序图等专用入口。下表只用于选型，不把任何一项写成标准符合性保证。
| 比较维度 | Mermaid | PlantUML |
|---|---|---|
| 文档内流程与常见关系图 | 适合作为日常默认工具 | 能表达，但通常在专用设计图中更有价值 |
| 类与组件边界 | 可表达基础关系 | 声明元素、关联类和视图裁剪选项更多 |
| 复杂交互与状态机 | 可覆盖常见场景 | 有更多专用交互、状态和控制表达 |
| 数据建模 | 擅长紧凑的 Crow's Foot schema 图 | 另有 Chen 概念建模模式 |
| 架构与 C4 | 可用于服务地图，C4 当前仍标为 experimental | 组件、部署与 C4-PlantUML 更适合做架构基线 |
| 团队策略 | 用于高频、短反馈的文档图 | 用于需要长期沉淀的设计图 |
版本前提不可省略
Mermaid 的图型能力会随版本演进，选型时要把官网资料和实际渲染环境分开。以泳道图为例，官方文档标注独立 swimlane-beta 图型需要 11.16.0+，而本项目锁定 11.6.0；这类差异应在采用新语法前确认。PlantUML 的专用图语法也应以团队使用的渲染版本和已验证输出为准。
Mermaid 和 PlantUML 分别是什么？
Mermaid 是 diagram-as-code 工具，其官方文档将 Flowchart、Sequence、Class、State、ER 等作为独立图类型维护。它的价值是把图放进日常文档的更新链路中，让图和文字、代码评审一起演进。
PlantUML 同样通过文本生成图，但为多个 UML 和架构表达场景提供专用语法。例如，组件图可声明组件与接口，部署图可使用节点、进程、数据库等元素。选择它不代表图会自动获得语义校验，而是团队可以使用更明确的表达词汇和图级控制。
专项文章从哪里开始读？
以下入口各自只回答一个问题，避免把同一结论在总览页重复展开。
- 时序图对比：常规消息交互两者都能表达；需要
return、autoactivate、ref over或拆页时，PlantUML 的专用语法更多。 - 类图对比：正式类图优先 PlantUML，依据是显式声明元素、关联类与
hide/show/remove/restore，而不是嵌套 namespace，因为 Mermaid 11.15.0+ 已支持它。 - ER 图对比：应用 schema 倾向 Mermaid 的 Crow's Foot 和键标记；需要 Chen 概念模型时选 PlantUML。
- 活动图对比：Mermaid 可用 Flowchart 描述活动流程；PlantUML 提供
if、repeat、while、fork等专用控制语法。 - 泳道图对比：职责归属和跨角色流程优先评估 PlantUML；Mermaid 的独立泳道图从 11.16.0 起提供，需同时确认版本前提。
- 状态图对比：普通状态流可用 Mermaid；浅深历史和进入、退出点等设计需求优先 PlantUML。
- 软件架构图对比：服务或资源总览可考虑 Mermaid Architecture Diagram；组件、部署与复杂架构设计默认 PlantUML。
- C4 图对比：C4 架构基线优先 C4-PlantUML；截至核验日，Mermaid 官方仍将 C4 标为 experimental。
团队怎样并行使用两种工具？
将工具边界写进团队约定，比强制所有图统一一种语法更可靠。可以规定：文档作者先用 Mermaid 表达变化快的流程和说明；涉及架构评审、可复用的模型边界或专用 UML 表达时，再创建或维护 PlantUML 源文件。两类图应链接到同一需求、ADR 或模块说明，避免同一事实在两处独立漂移。
迁移时先盘点现有图的读者和维护周期。高频修改、信息密度适中的图可以保留或迁至 Mermaid；承担设计决策、包含复杂结构的图保留在 PlantUML。不要承诺两者可以无损互转，尤其是高级 stereotype、样式与工具专用语法。
常见决策问题
总体来说，谁更强？
若比较日常文档内的常见图表，Mermaid 更适合作为默认工具；若比较正式设计文档中的类、组件、部署、复杂交互和状态机表达，PlantUML 的专用语法范围更广。团队应将 Mermaid 用作日常文档默认工具，并将 PlantUML 用作正式设计文档和复杂架构图的默认工具。
Mermaid 和 PlantUML 可以混用吗？
可以，且多数同时维护产品文档与架构设计的团队都应混用。用 Mermaid 处理高频、近代码的说明图，用 PlantUML 记录需要长期维护的设计表达；在同一文档中明确图的目的和源文件位置即可。基础语法相近不代表高级语法、样式或专用能力能够无损转换。
PlantUML 等于语义模型工具吗？
不等于。PlantUML 提供更丰富的声明元素、专用图类型和样式、视图控制语法，但这些语法本身不会自动验证领域模型、数据库约束或 UML 标准符合性。模型语义仍应通过命名、评审、代码与设计流程共同维护。
团队迁移时应该怎么选？
先按图的用途分组，再做小范围迁移。把 README、PR 和 Wiki 中频繁更新的图优先迁到 Mermaid；保留架构评审、组件边界、部署关系及复杂状态和交互图的 PlantUML 源。涉及 Mermaid 官网新功能时，应先核对项目实际锁定的渲染版本。
如何开始执行？
先为每张新图标注用途：日常说明、数据 schema、设计评审还是架构基线。然后按本页的默认选择创建源文件，并从上方专项文章确认图型边界。这样做能让团队保留 Mermaid 的更新速度，也不丢失 PlantUML 在复杂设计表达上的空间。
需要在同一处编辑两种图时，可使用 OnUML 编辑器。