Mermaid：用 Markdown 写图表，文档告别"画图死"

写文档最烦的就是画图。好不容易画好一张流程图，需求改了，图又得重画。改着改着，图就比代码落后了几个版本，最后干脆没人维护了。Mermaid 就是来解决这个问题的——用写 Markdown 的方式生成图表，改需求就改几行文字的事。

Mermaid 是一个 JavaScript 写的图表工具，GitHub 上已经积累了 89,000+ Star。它的用法很直观：用类似 Markdown 的文本描述图表结构，Mermaid 自动渲染成 SVG 或 HTML。流程图、时序图、甘特图、类图、状态图、饼图，甚至 Git 分支图都能搞定。

举个例子，画个流程图只要几行：

flowchart LR A[Hard] -->|Text| B(Round) B --> C{Decision} C -->|One| D[Result 1] C -->|Two| E[Result 2]

看起来和写 Markdown 列表差不多，但渲染出来是一张规范的流程图。

为什么需要 Mermaid

文档和代码脱节是软件行业的顽疾。画图成本高，更新成本更高，于是图表就成了文档里最先腐烂的部分。Mermaid 的思路是把图表变成文本——文本可以版本控制、可以 diff、可以嵌入代码注释、可以集成到 CI/CD 流程里。

比如你在 GitHub 上写 README，直接用 mermaid 代码块就能渲染图表：

sequenceDiagram Alice->>John: Hello John, how are you? John-->>Alice: Great!

GitHub 在 2022 年已经原生支持 Mermaid 渲染，不需要任何插件。

支持哪些图表

Mermaid 目前支持的图表类型覆盖了日常开发的大部分场景：

• 流程图（Flowchart）：最基本的流程图，支持方向、分支、子图
• 时序图（Sequence Diagram）：展示对象之间的交互顺序，API 调用链、协议交互都能画
• 甘特图（Gantt）：项目排期、任务依赖，适合项目管理
• 类图（Class Diagram）：UML 类关系，Java/Python 项目常用
• 状态图（State Diagram）：状态机、工作流
• 饼图（Pie Chart）：数据占比，简单直观
• Git 分支图（Git Graph）：可视化 Git 分支合并历史
• C4 图：软件架构的层级描述，从系统上下文到容器、组件

每种图表都有在线编辑器可以实时预览，语法也不复杂，花 10 分钟看看例子就能上手。

实际体验

Mermaid 的语法设计得很克制。学过 Markdown 的人基本看一眼就能写。官方提供了 Live Editor，可以在浏览器里边写边看效果，零安装成本。

生产环境使用的话，可以直接引入 npm 包，或者在 CI 里用命令行工具把 .mmd 文件批量转成图片。文档项目可以统一用文本维护图表，再也不用手动截图替换了。

当然也有局限。复杂布局的图表（比如大型系统架构图）还是用专业绘图工具更顺手。Mermaid 的自动布局引擎适合中等复杂度的图表，太复杂的话布局会变得难以控制。但对于日常文档中 80% 的场景——流程图、时序图、甘特图——它完全够用。

适合谁用

• 写技术文档的人：把图表纳入版本管理，告别文档腐烂
• 项目经理：甘特图和流程图直接用文本维护，改排期不用重画
• 开源项目维护者：README 里的架构图随代码一起更新
• 任何想减少重复劳动的人：画图是个体力活，让机器干更划算

Mermaid 被 JS 开源奖评为 2019 年"最激动人心的技术应用"，从结果看实至名归。它解决的是文档领域一个小而痛的缺口，方案也足够优雅——让图表回归文本，让文档重新跟上代码。

“最激动人心的技术应用”，从结果看实至名归。它解决的是文档领域一个小而痛的缺口，方案也足够优雅——让图表回归文本，让文档重新跟上代码。