Mermaid vs PlantUML vs D2：哪个更好？· 2026

比较 Mermaid vs PlantUML vs D2 时，不存在所有场景都获胜的工具。三者都能把文本转换成图、进入版本控制，也都可以在不上传私有源码的情况下完成渲染。真正的区别在于自然工作环境：Mermaid 更贴近 Markdown，PlantUML 更贴近重度 UML 工程，D2 更贴近强调自动布局的架构设计。

这比单纯数功能更重要。一个工具即使支持所需图表，如果文档平台无法渲染、评审者看不懂源码，或 CI 难以维护，也不适合作为团队标准。下面从日常使用真正会遇到的决策逐项比较。

Mermaid、PlantUML、D2 快速对比

简单结论是：发布渠道最重要时选 Mermaid，建模语义最重要时选 PlantUML，自动布局最重要时选 D2。如果没有明显主导因素，不要只测 Hello World，而应拿项目里最复杂的一张真实图做原型。

同一个系统的三种语法

假设浏览器调用 API，API 再查询数据库。Mermaid 可以写成：

flowchart LR
    Browser --> API
    API --> Database

PlantUML 可以用组件和数据库元素表达：

@startuml
component Browser
component API
database Database
Browser --> API
API --> Database
@enduml

D2 的声明更隐式：

Browser -> API
API -> Database: query
Database.shape: cylinder

三段源码都能被 Git 追踪。模型变大以后差异才明显：Mermaid 在 README 中仍然紧凑；PlantUML 为不同图表提供更丰富的专用语义；D2 保持声明式模型，并把布局行为交给配置或渲染命令。

不要只凭语法喜好决定。更应该检查：新成员能否安全修改节点、评审者是否理解 diff，以及发布出来的图是否始终对应仓库源码。

Mermaid 适合什么场景

图表属于 Markdown 文档时，Mermaid 通常最有优势。它采用 JavaScript 渲染和类 Markdown 文本定义，很适合 README、架构决策记录、Pull Request 和文档站。官方语法目录已经覆盖流程图、时序图、类图、状态图、ER 图、甘特图、时间线、架构图和 Kanban 等多种类型。

Mermaid 的价值不只是容易学，而是发布摩擦小。平台已经支持 Mermaid 时，源码和图就在同一个文件里：贡献者修改代码块，评审者查看文本 diff，读者看到渲染结果，不必提交生成图片，也不用维护额外的图片地址。

以下情况优先选 Mermaid：

• 大部分图放在 Markdown 中；
• 团队需要容易上手的语法；
• 常用流程、时序、类、ER、状态和计划图已经够用；
• 原生渲染比切换布局引擎更重要。

大型关系图出现交叉线时，Mermaid 不一定容易调整；需要深入 UML 语义时也可能不够。不同平台内置的 Mermaid 版本还可能不同，新语法在在线编辑器成功，不代表旧文档平台也能渲染。

需要更细的两方比较，可以继续阅读 Mermaid 和 PlantUML 对比与 Mermaid 和 draw.io 对比。

PlantUML 适合什么场景

图表承担技术规格作用时，PlantUML 的优势更明显。它长期支持类图、时序图、活动图、用例图、组件图、部署图、对象图、状态图和时序图等类型。参与者、生命线、激活条、构造型、注释、分组与样式控制，适合需要精确 UML 沟通的团队。

PlantUML 也提供多种部署方式：本地 Java 命令、编辑器插件、CI、私有 PlantUML Server 或托管服务器。服务器可以把源码编码进 URL，并返回 PNG、SVG 等格式。这种灵活性适合成熟文档系统，但团队需要承担比原生 Mermaid 更多的渲染基础设施。

以下情况优先选 PlantUML：

• 正式或详细 UML 是核心需求；
• 时序图、部署图很复杂；
• 组织已经使用 Java、PlantUML 插件或私有服务器；
• 细粒度规范比最小安装成本更重要。

只有三个节点的 README 流程图没必要为此引入 PlantUML。但对 UML 仓库而言，按图表类型区分的明确语义正是优势，并不是累赘。

D2 适合什么场景

D2 把自己定义为声明式图表语言：描述有哪些对象、对象如何关联，再让渲染器生成图片。它的 CLI 默认把 .d2 源码编译成 SVG，也能输出 PNG，并提供监听、格式化、校验、主题和布局相关命令。

比较 Mermaid vs D2 时，关键差异是布局控制。D2 把布局引擎和相关配置作为工作流中的明确选择。对于架构地图、基础设施图和大型依赖关系图，逻辑模型可能保持不变，但不同布局策略会显著影响结果，这时 D2 很有吸引力。

以下情况优先选 D2：

• 主要产物是架构图或系统地图；
• 希望更换自动布局引擎，而不用重写模型；
• 本地 CLI 和生成 SVG 符合现有文档流程；
• 声明式源码比 Markdown 原生渲染更重要。

D2 在文档平台中的覆盖不如 Mermaid，正式 UML 深度也不如 PlantUML。没有 CI 生成图片时，读者可能只能看到源码，因此仓库必须明确记录渲染命令。

D2 vs PlantUML：架构还是 UML

理解 D2 vs PlantUML 最有效的方法，不是比较年龄或字符数量，而是明确源码要表达什么。

D2 更适合用方框和关系描述系统：服务、队列、存储、环境、所有权边界和数据路径。它的声明式结构与布局选择，能够在拓扑持续变化时保持模型可读。

PlantUML 更适合由符号本身传达工程含义的场景：参与者、生命线、激活状态、构造型、部署节点、类成员和可见性等。选择 PlantUML 等于选择更深入的建模词汇，而不只是另一种箭头写法。

非正式云架构总览可以先试 D2；详细时序契约或 UML 模型可以先试 PlantUML；如果架构总览必须直接出现在 Markdown 平台，Mermaid 仍可能凭发布便利胜出。

渲染、CI、隐私与安全

三种工具都能进入私有构建流程：Mermaid 可以在 Web 应用或 CLI 渲染，PlantUML 可以本地运行或部署私有服务器，D2 可以通过本地 CLI 编译。因此，“图表即代码”不等于必须把内部架构上传到公共服务。

实用的 CI 规则包括四步：校验源码、生成确定性产物、语法失败时阻断构建、把产物发布到文档旁边。原生支持 Mermaid 的平台可以不提交图片，但升级渲染器版本时仍应预览差异。PlantUML 和 D2 则应记录准确命令，避免本地与 CI 输出漂移。

不要在缺少隔离的情况下渲染不可信输入。应检查各渲染器的安全选项、持续更新依赖，并特别留意外部资源、链接、图标或服务端包含能力。图表源码本身也可能泄露内部服务名称和系统关系，应按技术文档的敏感级别管理。

按工作流选择，不要只数功能

可以按下面的顺序决策：

1. 读者在哪里看图？ 如果答案是 GitHub Markdown 或其他原生支持 Mermaid 的平台，先试 Mermaid。
2. 是否需要详细 UML 语义？ 如果需要，用 PlantUML 制作真实原型。
3. 自动布局是否反复造成问题？ 如果是，用 D2 渲染真实关系图并比较布局选项。
4. 谁负责编辑？ 开发者可能更喜欢文本，跨职能团队可能需要可视化画布。
5. 怎样发布？ 在创建大量源码文件之前，先固定渲染器版本和 CI 命令。

混合策略可以成立：普通文档用 Mermaid，UML 规格用 PlantUML，架构地图用 D2。但边界必须收紧。三种语法都随意使用，会增加评审成本，也让文档搜索和维护变得混乱。

落地时还应给每种格式准备一个最小示例和故障排查入口。示例要包含源码位置、预览方式、生成产物目录和版本升级方法。这样新成员不必先理解整套工具生态，就能修改现有图并确认结果。若某种格式连续数月只剩一两张图，应评估把它迁回团队主格式，减少长期依赖和安全更新成本。

如果只是一次工作坊或需要手工控制展示布局，图表即代码可能不是正确类别。此时可编辑流程图模板或免费时间线工具对非开发者更快。

最终建议

文档以 Markdown 为中心，默认选择 Mermaid；需要成熟 UML 表达，并能接受本地或服务器渲染流程，选择 PlantUML；架构图与可选择的自动布局最重要，选择 D2。

不要为了语法看起来更漂亮就迁移整个图库。只有当迁移确实解除限制——例如缺少所需符号、布局长期不可靠，或现有渲染流程无人愿意维护——才值得投入。用最复杂的真实图测试，衡量发布摩擦，最后统一到能够完成工作的最小工具集合。

相关阅读

• Mermaid 替代工具——继续比较其他图表即代码和可视化方案。
• Mermaid 和 PlantUML 对比——深入比较 Markdown 与 UML 工作流。
• PlantUML 替代工具——当安装或语法成为限制时选择替代品。
• Mermaid 时间线语法——通过可复制示例学习一种具体 Mermaid 图表。
• 免费流程图工具——当源码不是优先事项时比较可视化工具。