Mermaid 与图表画布对比：图表即代码何时适用，何时不适用

在工程团队里，很少有哪场工具之争能像这一场持续这么久。有人希望每张图都写成代码，用 Mermaid，在 pull request 里评审。也有人想要一块画布，可以随意挪动方框，看清整个系统。两边都没错，只是针对的图不同。

本文坦率地比较 Mermaid 和图表画布：各自擅长什么、在哪里力不从心、常见场景的决策表，以及用两种方式画出的同一个小系统。

Mermaid 擅长什么

Mermaid 能把几行文本变成一张图。这带来了实实在在的好处：

• 它和代码放在一起。 Markdown 文件里的图会和它所描述的代码在同一个 pull request 中修改，评审者能看到 diff。
• 它在工程师常待的地方直接渲染。 GitHub 和 GitLab 会在 Markdown 文件、issue 和 pull request 中渲染 Mermaid 代码块，Notion、Obsidian 等工具也能显示。
• 无需额外的工具或账号。 能编辑文件的人，就能编辑图。
• 时序图非常出色。 要表现四个服务之间的请求流程，Mermaid 的时序图语法很难被超越。
• AI 助手写起来很流畅。 让任何聊天助手画一张 Mermaid 流程图，大多数时候都能得到有效的语法。

Mermaid 的短板

• 布局不由你控制。 Mermaid 会自动摆放节点。加一条连线，整张图就可能重新排列；节点超过几十个之后，就很难看清了。
• 文本 diff 掩盖了视觉变化。 pull request 里一行的改动可能挪动半张图，而评审者只能看到那一行。
• 描述基础设施的词汇很贫乏。 流程图的形状都很通用。虽然有较新的架构图和 C4 图类型，但它们不如流程图和时序图成熟。
• 非工程师很少编辑它。 产品经理、设计师和支持团队能看懂结果，但通常不会改动源码。
• 没有共享的实时会话。 你在自己的编辑器里改文本；没有光标，没有实时评审，也没有人看着一项改动落地。

画布擅长什么

• 布局由你决定。 位置本身就承载含义：信任边界的划定、请求从左到右的流向、位于中间的集群。
• 带类型的节点和框。 在 Archboard 这样的画布上，Kubernetes Service 或 C4 容器是带端口的节点，namespace 或 VPC 则是容纳其内容的框。
• 人人都能编辑。 从不打开代码仓库的人，也能改正一个标签或添加一张便签。
• 实时协作与分享。 多人以及 AI 智能体可以带着光标一起编辑，实时链接或嵌入能让每位读者都看到当前版本。

画布的短板

• 除非更新它是你工作流程的一部分，否则它会与代码脱节。 画布默认不在 pull request 里。
• 有些格式不透明。 PNG 或专有格式的文件既无法做 diff，也无法生成。Archboard 通过 JSON 导出和公开的 JSON Schema 缓解了这一点，但 JSON 文档终究不是十行的 Markdown 代码块。
• 它需要一个工具。 读者无需账号就能查看分享链接，但编辑者需要账号。

决策表

规律是：图属于某一次变更、放在代码里时，Mermaid 胜出；图属于团队、比任何一次变更都存在得更久时，画布胜出。

同一个系统，两种画法

下面是用 Mermaid 写的一个小系统：

flowchart LR
  user([Customer]) -->|HTTPS| web
  subgraph shop [Online shop]
    web[Web app] -->|JSON| api[Orders API]
    api -->|SQL| db[(Orders DB)]
    api -->|OrderPlaced| q[[order-events]]
    q --> worker[Email worker]
  end
  worker -->|SMTP| mail[Email provider]

它易读，diff 清晰，GitHub 也能渲染。现在把同一张流程图放到画布上。我们把它交给一个通过 MCP 连接到 Archboard 的 AI 智能体，并附上从 Mermaid id 到节点类型的映射：user 对应 C4 人员，web、api 和 worker 对应 C4 容器，db 对应 Postgres，q 对应主题，mail 对应外部系统。智能体一步就画出了整张图，第二步再把它排成两行：

subgraph 变成了框，各个节点变成了带类型、带端口的节点。这个结果是一个起点，你现在可以像处理其他图一样调整布局、添加注释并分享。

有意识地两者并用

适合大多数团队的分工如下：

1. 属于某次变更的图，用 Mermaid。 设计文档和 pull request 中的时序图、代码旁的状态机、README 里的小型流程图。
2. 属于团队的图，用画布。 系统概览、基础设施、安全评审、新人上手。
3. 把两者连起来。 已经有 Mermaid 就从它开始：通过 MCP 连接到 Archboard 的智能体可以把 Mermaid 流程图转换成使用真实节点类型的画布图。需要和代码一起评审时，把画布导出为 JSON 放进代码仓库，并在 README 中链接到实时的图。

常见问题

可以把 Mermaid 粘贴到 Archboard 编辑器里吗？ 目前还不能直接粘贴。通过 MCP 连接的 AI 智能体可以把 Mermaid 流程图（包括 subgraph）画成使用真实节点类型的画布图。其他类型的 Mermaid 图（例如时序图）不会被转换。

画布上的图会出现在 pull request 里吗？ 不会自动出现。如果想和代码一起评审，就把它导出为 JSON 或 SVG 放进代码仓库，或者在 pull request 中链接到实时的图。

图表即代码一定更能保持最新吗？ 前提是有人去更新。没人碰的 Mermaid 代码块和画布一样会很快过时；区别在于，它离本该更新它的那次变更更近。

PlantUML 或 Structurizr 呢？ 取舍是一样的。PlantUML 擅长 UML 和时序图；Structurizr 专为以代码描述 C4 模型而设计。根据谁来编辑这张图、它需要存在多久来选择。

AI 助手更擅长处理哪一种？ 两种都行。助手能流畅地写 Mermaid，而通过 MCP，智能体也能直接编辑画布，大家可以实时看到改动，也能撤销。

免费开始 — 1 个席位，无需信用卡。