Mermaid流程图：文本化画图，告别手动重绘

使用 Mermaid 画流程图的团队，最后都会遇到同一个问题：图改了一版又一版，但每次修改都要在绘图工具里手动拖动节点、重新拉线、调整对齐。方案评审时改一版，开发实现时改一版，上线后运维同学又说要加个节点。等图终于稳定下来，你会发现花在"重新画图"上的时间，比花在"设计流程"上的时间还多。

这个局面在过去很长一段时间里是无解的。因为主流绘图工具都是"所见即所得"的逻辑：图是画出来的，不是写出来的。你拖一个方框，拉一条线，存成一个文件，这个文件跟代码仓库里的其他文件几乎没有关系。改了需求，就得回到画布里重新操作一次。

Mermaid 的出现改变了这个工作流。它的核心思路是用文本描述流程图，再用工具渲染成图形。也就是说，图的源文件就是一坨带标记的纯文本，改图等于改代码。这听起来很简单，但真正用到项目里，你会发现它改变的远不止"画图方式"这一件事。

这篇博客不打算只铺语法，而是先讲清楚一个关键问题：为什么"不用重画"对开发者意义如此重大。然后从实战角度拆解 Mermaid 的适用场景、语法核心、工程接入方式和坑点，最后给你一套可以直接套用的实践建议。

1. 这篇文章真正要解决的问题

如果你画流程图只是为了临时画一张给别人看，那任何绘图工具都没有区别。但如果你遇到的是下面几种情况，Mermaid 可能比你现在用的工具更合适：

第一，流程图需要频繁修改，而且修改粒度很小。比如加一个判断节点、改一个分支条件、调整节点之间的连接顺序。传统工具里，每一次改动都可能引发连锁的排版调整：节点间距变了、连线变乱了、整张图要重新拖一遍。Mermaid 里你只需要改一行文本，重新渲染，图就自动重新排布。

第二，流程图需要进入版本管理。代码仓库里最怕出现"图已经改了，但文档里的图还是旧的"这种情况。把流程图写成 Mermaid 源码放在项目仓库里，它就能被 Git 追踪，谁改了、改了什么、什么时候改的，全部有记录。而且代码评审的时候，评审者可以直接在 diff 里看到语法级别的变化，而不是看一张无法对比的图片。

第三，团队协作中流程图需要被复用。流程图不只是给一个人看的，它经常出现在架构文档、API 文档、技术方案、README、内部分享里。Mermaid 最方便的地方就在于，它已经深度集成到各类文档工具和代码托管平台中。GitHub、GitLab 原生支持 Mermaid 渲染，很多 Markdown 文档工具也带插件支持。你只要贴一段代码，别人看到的就是一张图。

第四，图的更新需要跟代码一起走。比如一个系统的模块划分、请求链路、部署架构，这些内容大概率随代码一起演进。Mermaid 源码和代码文件放在一起，提交代码时顺手更新图，文档和实现始终保持同步。这一点在长期维护的项目里非常值钱。

所以这篇文章的核心判断是：Mermaid 的价值不在于"能画图"，而在于"图和代码属于同一套工程体系"。它把画图这个动作从可视化的画布里解放出来，变成了工程产物的一部分。

什么样的读者最应该读完本文？写过技术文档、维护过老项目、经常给团队讲方案、或者只是想找个"不用反复调整格式"的图表方案的开发者，都会从中受益。

2. Mermaid 是什么：用文本描述图表的一种 DSL

Mermaid 是一个基于 JavaScript 的图表渲染引擎，也是一门轻量级的声明式图表描述语言。所谓"声明式"，指的是你只需要描述"图里有什么"和"这些内容之间有什么关系"，而不需要关心"具体怎么画出来"。

它支持多种图表类型，比较常用的有：

• 流程图（Flowchart）
• 时序图（Sequence Diagram）
• 状态图（State Diagram）
• 类图（Class Diagram）
• 甘特图（Gantt）
• 饼图（Pie）
• 需求图（Requirement Diagram）

在项目里用得最多的是流程图和时序图。流程图用来表达业务流程、系统模块、处理逻辑；时序图用来表达多个对象之间的消息交互顺序。

从技术角度理解 Mermaid，其实就是三个阶段：

1. 你用文本写图表的"源文件"，这个文件通常包含在 Markdown 文档里，或者是独立的 .mmd 文件。
2. Mermaid 解析器把这段文本解析成图结构的数据模型。
3. 渲染器根据这个数据模型，在浏览器里绘制出最终的 SVG 图形。

这个过程跟写 HTML 然后由浏览器渲染，在思路上很相似。你不控制每个像素的位置，只控制内容和关系，排版交给渲染引擎去完成。

这也解释了为什么它适合放进工程流程：源文件是纯文本，自然可以被 Git 管理、可以 diff、可以搜索、可以复用。而最终渲染出的 SVG 图片，也可以导出嵌入到其他文档里。

这里需要特别澄清一个容易混淆的概