PlantUML vs Mermaid 优缺点全景 + 选型决策树

这一篇是 PlantUML vs Mermaid 系列的第三篇。前面两篇（宏观对比 / 语法对照）打底之后，这一篇聚焦「我到底该选哪个」——把它切成 10 个强项 + 10 个弱项 + 一张决策树。

总览：两个工具的「性格」

PlantUML 的 10 个强项

1. UML 教科书级准确 — 类图、时序图、状态机的语义和 OMG 标准 1:1 对齐
2. 25+ 图类型 — UML 全家桶 + C4 + Archimate + AWS/Azure/GCP 库 + Salt + JSON/YAML，可视化覆盖最广
3. C4-PlantUML 是行业标准 — C4 架构图 90% 的现有文档都用 PlantUML 写
4. CLI 成熟 — plantuml -tpng file.puml 一行出图，CI 集成简单
5. 错误精确 — 语法错误时报错信息带行号 + 上下文，调试体验好
6. 预处理器 — !include、!define、!theme 让图可以模块化、模板化
7. 主题生态深 — 47+ 内置主题，可以内置到工程里
8. Enterprise 集成 — CI 渲染、批量渲染、回归测试（drift detection）成熟
9. 写出来的图可被解析 — 输出 SVG 是结构化的，可以二次加工
10. 命令行控制 — -pipe、-stdrpt、-checkonly 等让脚本化集成顺畅

PlantUML 的 10 个弱项

1. 依赖 JVM / Graphviz — 自托管要装 Java，对前端纯静态站点不友好
2. CI 体积大 — Docker 镜像 600MB+，CI 启动慢
3. 大图性能瓶颈 — Graphviz dot 在 1000+ 节点显著卡顿
4. 需要服务端渲染 — 浏览器实时预览要搭后端或用插件
5. CSS 不友好 — SVG 输出样式和 CSS 难以 override
6. 学习曲线 — UML 关键字多（+/-/-->/..>/..|>），新人要花时间
7. CJK 字体 — 跨语言字符需手动配置字体（!include <fonts/...>）
8. 版本节奏慢 — 一年 1-2 个 minor release，问题修复慢
9. Markdown 平台原生 — 不是 GitHub/Notion 的原生语法
10. 维护者少 — core 团队只有 2-3 人，关键 issue 排期慢

Mermaid 的 10 个强项

1. 零依赖 — 纯 JavaScript，浏览器 / Node 双端运行
2. Markdown 平台原生 — GitHub / Notion / 飞书 / Obsidian 都支持 ```mermaid
3. v11+ 语法贴近自然语言 — classDiagram / sequenceDiagram / flowchart，新人 5 分钟上手
4. GitHub README 之王 — 几乎所有开源项目都用 Mermaid 画流程图
5. 生态活跃 — GitHub commit 频率是 PlantUML 的 3-5 倍，问题修复快
6. 主题切换简单 — theme: forest/dark/neutral，3 行切换
7. 移动端友好 — 纯前端，移动浏览器渲染快
8. AI 友好 — Copilot / Cursor 训练集里 Mermaid 出现频率高
9. 支持交互 — v11+ click 指令、classDef 自定义样式
10. 版本节奏快 — 半年一个 major，跟随平台需求

Mermaid 的 10 个弱项

1. UML 严格度不够 — 类图实现、状态机嵌套等细节比 PlantUML 弱
2. C4 还在实验 — v11+ 才支持，API 经常变，文档跟不上
3. 大图性能 — 1000+ 节点仍然卡（虽然 v12 改善）
4. 跨图引用不成熟 — ref 指令 v11+ 才有，bug 多
5. 状态机并发 — 不支持 || 并发区
6. 错误信息弱 — 语法错误经常报「syntax error」一行，定位难
7. 样式扩展有限 — classDef + theme 之外，结构层扩展基本封顶
8. ER 图弱 — 不能直接表达弱实体、继承
9. CLI 慢 — @mermaid-js/mermaid-cli 启动慢（puppeteer 依赖）
10. 某些企业内网环境 — 浏览器 JS 沙箱限制（不只是 Mermaid，所有前端 DSL 都受限）

跨维度对照表

决策树：30 秒选型

把上面的维度浓缩成一张决策树：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

Q1. 你画图是为了 Markdown / GitHub README / Notion / 飞书 文档？
    ├─ 是 → 走 Mermaid 路径
    └─ 否 → Q2

Q2. 你需要 C4 / Archimate / AWS / Azure 等架构图？
    ├─ 是 → 走 PlantUML 路径
    └─ 否 → Q3

Q3. 你的图是不是严格 UML（类图、时序图、状态机）？
    ├─ 是 → 走 PlantUML 路径
    └─ 否 → Q4

Q4. 你需要在 CI 里批量生成 / 校验图？
    ├─ 是 → 走 PlantUML 路径
    └─ 否 → Q5

Q5. 你的团队成员是不是写代码的工程师？
    ├─ 是 → 两个都行；PlantUML 更精，Mermaid 更易
    └─ 否 → Mermaid（非工程师 5 分钟上手）

PlantUML 路径上的分支：
  需要纯前端实时渲染？ → 考虑 Mermaid 或前端 PlantUML 服务
  CI 启动慢？ → 考虑缓存 / 预渲染

Mermaid 路径上的分支：
  需要 C4 / 复杂状态机？ → 退到 PlantUML
  报错定位困难？ → 用 Mermaid Live Editor 在线调试

真实场景的硬经验

场景 1：写 GitHub README

选 Mermaid。

• GitHub 原生 ```mermaid 块，不用任何配置
• v10+ 主题、点击、注释都支持
• 缺点：复杂图可能渲染时间 > 5 秒（GitHub 限制）

实战 tip：

• 优先用 flowchart / sequenceDiagram（社区验证最多）
• 状态机用 stateDiagram-v2（v1 已废弃）
• 复杂类图别用 Mermaid（落到 PlantUML 或换文档站）

场景 2：企业内网架构图（Java 团队）

选 PlantUML。

• C4-PlantUML 是行业标准
• 自托管 jar / Docker，CI 集成简单
• 团队里都是 Java 工程师，DSL 学起来不费力

实战 tip：

• 用 !include <C4_Container> 复用 C4 模板
• 用 !theme 锁定公司品牌色
• 通过 pre-commit hook 校验图源码

场景 3：博客 / 个人项目

选 Mermaid。

• 零部署成本
• 主题切换方便
• 跨语言友好（CJK / emoji 默认支持）

实战 tip：

• Hexo 装 hexo-filter-mermaid-diagrams 即可
• 复杂图分多个 mermaid 块写，控制单图节点数 < 80

场景 4：CI 自动生成 + 校验图

选 PlantUML。

• plantuml -checkonly 校验图语法，CI 失败即拦截
• 错误信息带行号 + 上下文
• 批量渲染脚本好写

实战 tip：

• 用 plantuml -stdrpt 报告生成图列表
• 在 pre-commit 跑 plantuml -tpng -failfast2 阻断 push

场景 5：跨语言 / 国际化文档

优先 Mermaid。

• 默认支持 CJK、emoji、阿拉伯文、RTL
• PlantUML 需要 !include <fonts/notosans> 之类配置

实战 tip：

• Mermaid v11+ 开始原生支持 RTL
• 若必须用 PlantUML，配 Google Noto Sans CJK 字体

场景 6：AI 协作 / Copilot 写图

Mermaid 略胜。

• 在 Copilot / Cursor 训练集里出现频率更高
• 但两者都能由 LLM 生成

实战 tip：

• prompt 里明确写语法（”用 graph TD” / “用 @startuml”）
• 提供 1-2 个示例让 LLM 学风格
• 复杂图让 LLM 先给 outline，再人工修正

经验之谈（团队选型）

用 Mermaid 的团队：

• 文档驱动（写作 > 写代码）
• 跨职能（产品 + 设计 + 工程师）
• Markdown 文档站为主

用 PlantUML 的团队：

• 软件工程导向（写代码的人为主）
• 严肃 UML / 架构图
• 自动化 CI / 强校验

混用的团队（最常见）：

• 产品文档 / README / 飞书 → Mermaid
• 架构图 / CI / 规约 → PlantUML
• 约定俗成的「在哪画什么」

切换成本

两个工具的迁移成本都不小，不要轻易换：

• PlantUML → Mermaid：复杂图（state、ER）会丢属性，主题需要重写
• Mermaid → PlantUML：组件图、系统图需要重新设计（结构差异大）

建议：团队选型前做 1-2 周试点，让 3-5 个真实场景的图过两边，看哪个综合胜出。

走向 2027

Mermaid 持续在涨（GitHub / Notion / 飞书平台原生），PlantUML 稳态（Java 工程师 / 企业架构）。

预测：

• Mermaid 会继续吃掉「简单流程图」市场
• PlantUML 会守住「严肃 UML / C4」市场
• 两者都不会消失，但混用会成为主流

决策一句话总结

Mermaid 给文档写作者，PlantUML 给写代码的工程师。

如果你的团队是「写代码的人」，选 PlantUML。
如果你的团队是「写文档的人」，选 Mermaid。
如果都有，建议混用：文档 Mermaid + 架构 PlantUML。

延伸阅读

• 上一篇：PlantUML vs Mermaid 语法逐图对照：7 种常用图对照
• 上上篇：PlantUML vs Mermaid 宏观对比：两种「文本画图」哲学
• 跨工具迁移：PlantUML 跨工具迁移实战：迁到 D2、Mermaid、Draw.io