只有三分钟的赛雷去年我在团队里整理一份服务接入文档，系统里涉及登录、限流、回调、告警四条链路。用画图工具画了一下午，刚保存完产品过来说流程改了。我那个瞬间真的想把显示器关了。后来同事说：要不你试试Mermaid，把图写成代码，放进Markdown里，改的时候只改箭头就行。当天我把所有链路图重写成了Mermaid源码，从那以后，文档里任何一张图都能跟着代码一起Review了。
这篇东西我不想写成一份逐条罗列的官方语法手册，而是按我实际的使用路径来聊：先搞清楚Mermaid解决了什么问题，再上手画第一张流程图，接着扩展到时序图、状态图、甘特图这些常用图型，然后聊Live Editor、CLI和API这三件套怎么提高效率，最后重点讲一讲跨平台兼容——毕竟代码写得再漂亮，放到不支持的平台上渲染不出来也是白搭。适合正在写技术文档、项目README、内部Wiki，以及想在博客或代码仓库里放图的人参考。
1. 为什么把图画成文本：从“改图艰难”到“图随代码走”
1.1 传统画图工具的痛，都是在改动时爆发
接触Mermaid之前，我很长一段时间都在用Visio和draw.io画架构图。单张图刚画完的时候确实挺好看，但问题从来不出在“画出来”那一刻，而是出在“要改”那一刻。
传统绘图文件大多是二进制格式或私有XML格式，离开对应工具根本打不开。你想让不熟悉这个工具的人帮你改一条线，要先教他装软件、学操作。更难受的是，这类文件进了Git之后，你没法像看代码一样看一张图到底改了什么，只能打开两个版本对比，肉眼找差异。团队里一旦有多个人同时维护一张架构图，很快就分不清谁改过哪一版了，历史上一团乱麻。
还有一类常见场景：代码逻辑变了，图却没有跟着变。很多人不是不想更新文档，而是改图成本太高——先要找到源文件，再拖线、拽框、重新导出、替换图片。流程一多，图的维护者干脆放弃了，最后文档里挂着一张“仅供参考”的历史图。
1.2 Mermaid把图形变成代码之后，发生了哪些变化
Mermaid的核心思路特别朴素：用类似Markdown的文本语法描述图形，然后由解析器渲染成SVG。你不需要关心画布坐标，不需要手动对齐节点，只要写下节点和连线之间的关系，渲染引擎会帮你排布。
图变成文本之后，最直接的好处就是可以进Git做版本管理。每次改动都能看到diff，A节点指向B节点改成了指向C节点，清清楚楚。代码评审的时候，图和代码在同一次MR里出现，逻辑变更一目了然。文档不再是事后补的“成品”，而是跟代码一起演化。
Mermaid还有另一个隐藏优势：它天然适配如今的内容生态。GitHub仓库的README可以直接渲染，很多笔记软件和在线文档平台也支持Mermaid代码块。你在本地写好的图，复制粘贴到支持Mermaid的平台，不需要再传图片，渲染由平台自动完成。
1.3 Mermaid不是万能的，它的适用边界要心里有数
我也见过一些不太合适的用法。有人试图用Mermaid画一张包含上百个节点的完整网络拓扑，结果渲染出来连成一片，可读性反而比手绘图差。有人追求极其精细的视觉设计，要求每个节点阴影、圆角完全一致，这也超出了Mermaid的定位。
文本化绘图适合的是结构清晰、节点数量适中、需要频繁维护的场景，比如流程图、时序图、状态机、部署关系、数据库ER图。如果你的图主要价值在视觉冲击力，或者需要像素级控制布局，建议还是用专业设计工具或绘图软件，导出图片之后用Mermaid画局部补充。判断标准很简单：这张图未来会不会改？会改就值得用文本描述，不会改怎么画都行。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 从第一张flowchart开始：读懂Mermaid图表编译语法
2.1 五行代码看懂一个流程图
Mermaid图表编译语法没有想象中复杂，核心就两样：节点怎么声明、节点之间怎么连线。先看一张最常见的登录鉴权流程图，源码就几行：
text复制flowchart TD
A[收到请求] --> B{权限校验}
B -- 通过 --> C[调用业务服务]
B -- 不通过 --> D[返回 403]
C --> E[写入审计日志]
第一行的 flowchart TD 是声明，表示这张图画的是流程图，方向是从上到下（TD = Top Down）。如果想从左侧往右侧排，可以写 flowchart LR，L是Left，R是Right。
接着每一行定义节点和连线。A[收到请求] 中，A 是节点ID，方括号里的“收到请求”是显示文本。B{权限校验} 中的花括号表示这是一个判断节点，渲染出