之前帮团队整理技术方案文档时最头疼的不是写文字而是画流程图。需求评审会上用 draw.io 拖矩形、拉箭头好不容易把布局对齐产品经理一句话“这个分支顺序要调整”又得重新拖动、重新连线。后来切到 Mermaid 之后这个问题基本消失了流程图的源码就写在文档里改文字、改分支、改方向都像改代码一样保存即渲染再也不用“画”图了。这篇文章围绕 Mermaid 流程图展开整理了一套从基础语法到团队协作完整落地的方法。适合被图形化编辑器困扰的后端开发、运维、项目文档维护者也适合刚开始接触 Mermaid 的新手。读完你能掌握 Mermaid 的流程图语法、常用工具链、从零到一的实战示例以及常见的渲染报错排查思路。1. Mermaid 是什么为什么你不需要再“重绘”流程图1.1 传统图形编辑器遇到的真实痛点谈 Mermaid 之前先回顾一下传统“画图”方式里的常见问题。大部分团队画流程图会选择 draw.io、ProcessOn、Visio 或者在线白板。这些工具的优势是所见即所得鼠标拖拽就能完成但真正进入项目文档维护阶段后痛点会越来越明显流程图和代码仓库是分离的。设计文档里的图片是一张静态 PNG评审时发现逻辑改了要么重新打开源文件要么对着图片重新画一张。对齐和排版消耗大量时间。同一个流程节点多了以后手动摆放位置很费劲连线一多箭头交叉、标签重叠都很难处理。难以版本对比。流程图源文件通常是 XML 或私有格式Git 里的 diff 基本不可读想追溯“上一次这个判断条件是什么”非常困难。协作成本高。产品、开发、测试在不同工具中打开同一个图容易出现“图已过期”的情况。这些问题的根源是图形化编辑器把“流程内容”和“图表样式”绑定得太紧导致维护时永远在重新排版而不是修改逻辑。1.2 Mermaid 的核心思路图表即代码Mermaid 是一个基于 JavaScript 的图表绘制工具它允许用户用类似 Markdown 的文本语法来描述图表结构然后由解析器渲染成 SVG 或 PNG。也就是说流程图的“源文件”是一段纯文本而不是一堆坐标信息。以最基本的 flowchart 为例下面这段文本就是一张完整流程图graph TD A[开始] -- B{是否注册} B -- 是 -- C[登录] B -- 否 -- D[注册] C -- E[进入首页] D -- E复制这段文本到 Mermaid Live Editor、VS Code 插件或者支持 Mermaid 的文档平台中就能渲染出一张清晰的流程图。因为源文件是纯文本所以它天然适合放进 Git 仓库做版本管理。团队里任何人修改了逻辑代码评审时能直接看到哪一行分支发生了变化。简单说Mermaid 要解决的核心问题就是让你把画流程图的时间用来梳理逻辑而不是用来拖动矩形框。这也是“Show HN: Mermaid flowcharts you dont have to redraw in a diagram editor”这个项目标题最想表达的价值——你不需要在另一个图形编辑器里把同样的流程重新画一遍用文字描述完就有一张可维护的图。1.3 典型应用场景根据实际使用经验Mermaid 比较适合以下几类场景技术方案文档和架构文档直接内嵌在 Markdown 里方便阅读和更新。README 中展示项目启动流程、数据流向、模块关系。运维手册中的部署流程、故障处理分支、定时任务逻辑。项目交接文档用代码描述流程后来者能快速追踪修改历史。API 设计、数据库 ER 图、时序图等需要频繁更新的图。当然Mermaid 并非要替代所有绘图工具。界面设计稿、复杂部署拓扑、需要精细视觉调整的汇报 PPT用专业绘图工具仍然更合适。Mermaid 的优势在于“够用、好维护、可版本化”这也是它在开发者社区快速流行的主要原因。2. 环境准备与工具链选择Mermaid 的使用方式非常灵活可以零安装直接在线使用也可以在本地配合 VS Code 或命令行工具使用。下面介绍三种常见方案按需求选择即可。2.1 方案一Mermaid Live Editor零安装起点对于初学者最推荐先打开 Mermaid Live Editor。这是一个官方提供的在线编辑页面左边写代码、右边实时渲染适合快速验证语法。操作方式很简单打开 Mermaid Live Editor 网页。左侧输入区域粘贴 Mermaid 代码。右侧会自动渲染图表。顶部可以导出 PNG/SVG也可以直接分享链接。不需要任何注册和安装。很多开发者第一次接触 Mermaid 都会先用它验证语法。需要注意在线工具依赖网络生成的链接也可能有有效期团队正式文档中不建议长期依赖在线页面保存内容代码本身应该放在仓库里。2.2 方案二VS Code 本地预览插件日常写 Markdown 文档时我推荐在 VS Code 中安装 Mermaid 预览插件。主流方案有两种Markdown Preview Mermaid Support在 Markdown 预览中直接支持 Mermaid 代码块解析。Mermaid Preview单独打开一个预览面板专门查看当前 Mermaid 图表的渲染效果。安装后在 VS Code 中新建一个.md文件写入 Markdown 格式的 Mermaid 代码块再用快捷键CtrlShiftVWindows或CmdShiftVmacOS打开预览就可以边写边看。对经常维护技术文档的开发者来说这一步能显著提升体验。插件版本和 VS Code 版本有关安装后如果预览没有生效检查一下插件是否启用或者重启 VS Code。版本差异导致的问题优先查看插件主页的说明。2.3 方案三mermaid-cli 命令行批量导出如果需要在 CI 流水线中自动生成图片或者在本地批量把多个 Mermaid 文件导出为 PNG/SVG/PDF可以使用 mermaid-cli它是一个基于 Node.js 的命令行工具。安装时需要 Node.js 环境并使用 npm 全局安装npm install -g mermaid-js/mermaid-cli安装完成后假设有一个flow.mmd文件内容是一段 Mermaid 源码可以通过mmdc命令导出图片mmdc -i flow.mmd -o flow.png也可以导出为 SVGmmdc -i flow.mmd -o flow.svg实测中mermaid-cli 需要依赖 Chromium 进行渲染首次运行时可能会下载浏览器组件耗时较长。在部分 Linux 服务器上还需要手动安装字体库避免中文显示成方块。这个方案的灵活度最高适合自动化文档生成场景。3. 流程图核心语法拆解Mermaid 的 flowchart 语法并不复杂但有几个关键点需要理解。掌握这些基础后大部分流程图都能直接用文本描述出来。3.1 图表声明与方向流程图文本的第一行是图表声明格式为graph 方向或者使用旧版关键字flowchartflowchart TD两种写法都表示“这是一张流程图”。方向关键字控制整体布局走向TD/TB从上到下Top Down / Top Bottom。BT从下到上。LR从左到右Left Right。RL从右到左。实际项目里业务流程图常用TD因为阅读习惯是从上到下模块架构类图可以用LR横向展示并列关系。3.2 节点定义与形状Mermaid 中节点的常见写法是节点ID 形状 节点文字。A[开始] B(处理中) C{是否满足条件} D[(数据库)]不同形状代表的语义如下形状写法示例常见含义A[文本]矩形普通操作步骤B(文本)圆角矩形操作或事件C{文本}菱形判断/分支D[(文本)]圆柱形数据库或存储E([文本])体育场形开始/结束F[[文本]]子程序样式调用子流程G[/文本/]平行四边形输入/输出注意节点 ID 是标识符不一定会显示在图片中。如果想在图上显示指定文字就在形状括号里写如果想让 ID 和文字一致可以直接写开始 -- 结束这里“开始”和“结束”既是节点 ID也是显示文字Mermaid 默认会渲染成矩形。注意节点文字如果包含特殊字符比如中文括号、冒号、引号建议用引号包起来例如A[用户点击“提交”按钮新窗口]这样能避免解析错误。3.3 连线方式与语义流程图的核心是节点之间的连接。Mermaid 支持多种连线样式A -- B // 实线箭头表示流程方向 A --- B // 实线无箭头表示关联 A -.- B // 虚线箭头表示异步或弱依赖 A B // 粗线箭头表示重点流转 A -- 是 -- B // 带文字标签的箭头 A -. 失败 .- C // 带文字标签的虚线箭头分支场景下带标签的箭头非常实用graph TD A{用户是否登录} -- 已登录 -- B[进入工作台] A -- 未登录 -- C[跳转登录页]这里A是菱形判断节点两条边分别标注“已登录”和“未登录”渲染后就是正常的判断分支图。3.4 子图与分组当流程较长时可以用subgraph把相关节点放进同一个组形成“泳道”或“区域”的概念graph TD subgraph 前端 A[用户填写表单] B[提交请求] end subgraph 后端 C[参数校验] D[业务处理] end A -- B -- C -- Dsubgraph后面的文字是子图标题子图内部的节点和其他子图之间也可以互相连线。使用子图能让复杂流程图保留清晰的阅读层次。3.5 样式定制Mermaid 默认有不错的配色但有时我们也需要高亮关键节点例如标红异常分支。支持两种方式。方式一单独给某个节点设置样式style B fill:#ffcccc,stroke:#cc0000,stroke-width:2px方式二通过classDef定义样式类然后给多个节点应用classDef error fill:#ffcccc,stroke:#cc0000,stroke-width:2px class C error也可以把类名直接写在节点定义中D[服务异常]:::error实际使用时要注意不要为了美观堆太多颜色。流程图的重点是逻辑可读样式只要突出“正常路径”和“异常路径”即可。4. 完整实战把业务文档中的流程图“代码化”下面用一个电商退货流程作为例子演示从需求描述到 Mermaid 源码再到导出图片的完整过程。这段内容可以直接套用到自己的业务文档中。4.1 需求与原始流程假设产品经理给出的需求描述如下用户发起退货申请系统先判断订单是否超过退货期限。超过期限则拒绝退货流程结束未超过期限则进入审核环节自动审核通过后进入仓库收货环节。若自动审核不通过则需要人工审核。人工审核驳回则拒绝退货人工审核通过则进入仓库收货。仓库收到退货后系统退款流程结束。直接看文字比较费劲如果还在用图形编辑器接下来就要打开 draw.io 画矩形了。而现在我们直接把它转换成 Mermaid。4.2 用 Mermaid 描述主流程先根据文字拆出核心节点用户发起退货申请。是否超过退货期限。拒绝退货。自动审核。人工审核。仓库收货。系统退款。先把主干流程写出来graph TD A[用户发起退货申请] -- B{是否超过退货期限} B -- 是 -- C[拒绝退货] B -- 否 -- D[自动审核] D -- 通过 -- E[仓库收货] D -- 不通过 -- F[人工审核] F -- 驳回 -- C F -- 通过 -- E E -- G[系统退款]这段代码渲染后就是一张标准的退货判断流程图。文字描述里的逻辑分支都对应到具体的箭头和节点上。4.3 加入子图与样式为了让这张图更接近项目文档的视觉效果可以增加子图把用户操作、系统判断、仓库处理分成三个区域graph TD subgraph 用户端 A[用户发起退货申请] end subgraph 系统处理 B{是否超过退货期限} D[自动审核] F[人工审核] C[拒绝退货] end subgraph 仓库与财务 E[仓库收货] G[系统退款] end A -- B B -- 是 -- C B -- 否 -- D D -- 通过 -- E D -- 不通过 -- F F -- 驳回 -- C F -- 通过 -- E E -- G classDef process fill:#e1f5fe,stroke:#0288d1; classDef warning fill:#fff3e0,stroke:#f57c00; classDef endNode fill:#c8e6c9,stroke:#388e3c; class A,D,F process; class B warning; class C,E,G endNode;这里给不同语义的节点设置了不同颜色蓝色系表示一般处理过程橙色系表示判断绿色系表示流程结束或成功节点。类名规则建议结合团队规范不要随意起名。4.4 增加交互点击跳转在团队内部知识库中更进阶的用法是给节点添加跳转链接。点击“人工审核”节点可以跳转到审核规则文档click F https://example.com/audit-rule 查看审核规则这个语法在 Mermaid 渲染为 HTML/SVG 时支持点击导出 PNG 时则没有交互效果。适合部署在内部 Wiki 或者企业知识库中。4.5 通过命令行导出 PNG/SVG如果最终需要把图片插入到传统 Word/PDF 文档中可以用 mermaid-cli 导出。新建return-flow.mmd文件内容为上面最终版 Mermaid 源码然后执行mmdc -i return-flow.mmd -o return-flow.svg --width 1024如果生成图片中发现中文字体缺失需要先确认系统中安装了中文字体比如 Noto Sans CJK。Linux 服务器环境下最容易遇到这个问题。导出后检查图片中文字是否完整连线是否有重叠。Mermaid 自动排版在节点较少时表现很好节点超过二三十个时建议用子图拆分或者考虑拆成多张子流程图。5. 不只是流程图时序图与状态图也能“代码化”掌握 flowchart 后Mermaid 的其他图表能力也非常推荐掌握。团队文档中高频使用的主要有时序图和状态图。5.1 时序图描述接口调用过程时序图用于描述多个参与者之间的消息交互最典型的场景是接口调用流程。Mermaid 语法示例sequenceDiagram participant U as 用户 participant C as 客户端 participant S as 服务端 U-C: 点击提交订单 C-S: POST /api/order S--C: 返回订单ID C--U: 展示下单成功关键字说明participant定义参与者as后面是显示名称。-表示实线箭头--表示虚线返回。冒号后面写的是消息内容。时序图非常适合补充到接口设计文档中比一长串“请求-响应”文字说明直观得多。5.2 状态图描述对象状态流转状态图适合描述一个对象在不同事件驱动下的状态变化。比如订单状态stateDiagram-v2 [*] -- 待支付 待支付 -- 已支付: 支付成功 待支付 -- 已取消: 超时取消 已支付 -- 已发货: 商家发货 已发货 -- 已完成: 用户确认收货 已支付 -- 已退款: 用户申请退货stateDiagram-v2是 Mermaid 推荐的状态图声明方式。[*]表示初始状态或结束状态。冒号后面写的是状态发生转移的触发条件。5.3 其他常用图表除了流程图、时序图、状态图Mermaid 还支持classDiagram类图适合描述系统类结构和关系。erDiagram实体关系图适合数据库设计文档。gantt甘特图适合项目管理排期。pie饼图适合简单占比统计。journey用户旅程图适合用户体验地图。上述图表语法结构类似都遵循“声明图类型 定义元素 定义关系”的思路。完整语法建议以 Mermaid 官方文档为准不同版本对某些图表的支持程度有差异遇到语法不生效时优先查官方示例。6. 常见问题与排查思路Mermaid 使用过程中最容易被语法细节绊住。下面整理了几个高频问题按“现象 → 原因 → 解决”的顺序展开。问题现象常见原因解决思路渲染区域显示语法错误提示箭头符号或括号不匹配检查节点形状括号是否闭合箭头是否写成中文符号中文节点文字乱码或显示成方块导出环境缺少中文字体安装 Noto Sans CJK 或其他中文字体SVG 中检查 font-family箭头上的文字重复展示节点 ID 和显示文字混用给节点显示文字用引号包裹或者使用-- 文字 --语法子图内容不显示subgraph结束缺少end检查每个子图是否有配对的end关键字菱形判断节点文字过长图片被拉伸节点文字太长导致排版异常精简节点文字或拆分为两个判断节点使用旧版语法渲染异常Mermaid 版本升级后关键字变更比如stateDiagram建议换成stateDiagram-v2以官方文档为准click跳转链接不生效导出为 PNG 时本身不支持交互使用支持交互的 HTML/SVG 形式或在文档平台内嵌源码Live Editor 打不开网络不稳定或浏览器缓存问题刷新页面或切换到 VS Code 本地预览方案其中最常见的问题是中英文符号混写。Mermaid 语法要求使用英文冒号、英文括号、英文箭头。如果从聊天消息复制代码到编辑器中很可能会把中文冒号带进去导致解析失败。遇到渲染错误第一步先检查符号的全半角。另外节点文字中如果包含()、[]、{}建议统一用双引号包裹整个文本A[订单状态(待支付)]这样可以减少解析歧义。还有一个容易被忽略的点Mermaid 中有些符号是保留字比如end、subgraph、graph。如果节点 ID 使用了这些词会导致解析异常建议在节点 ID 或文字上避开或者用引号明确包裹。7. 最佳实践与工程建议掌握了语法更重要的是如何在团队中真正落地。下面几条工程经验来自维护多份技术文档的实际总结。7.1 图表文件进入版本库尽量把 Mermaid 源码放在 Git 仓库中而不是只放一张导出后的 PNG。推荐目录结构docs/ ├── diagrams/ │ ├── return-flow.mmd │ ├── order-state.mmd │ └── api-sequence.mmd └── README.md.mmd是 Mermaid 源码的常用扩展名。提交代码时Git 可以清晰展示每次修改了哪个节点、哪条连线Code Review 的成本远低于对比两张图片。如果团队需要把生成的图片也入库可以在提交前统一重新生成并约定“图片是由源码生成的不要手动编辑图片”。7.2 保持图表的单一职责一张图只表达一个核心流程。如果一个流程图超过 20 个节点阅读体验会明显下降。此时建议拆分成多张子图然后通过链接或文字说明串联。例如订单全流程可以拆成“下单流程”“支付流程”“退货流程”“退款流程”分别维护而不是画一张巨大的全景图。这样既方便在文档中引用也减少后续修改时的冲突。7.3 命名与注释规范节点 ID 建议使用有语义的英文缩写并保持全图统一。不要出现A、B、C这种无意义 ID否则后续维护时很难定位。在 Mermaid 源码中也可以加注释%% 退货主流程 graph TD A[用户发起退货申请] -- B{是否超过退货期限}用%%开头的是注释行渲染时不会显示。注释可以用来标注维护人、修改日期、业务规则来源方便后续排查。7.4 与文档平台的集成如果你所在团队使用 GitLab/GitHub 管理文档仓库内置的 Markdown 渲染通常直接支持 Mermaid 代码块。部分企业自建 Wiki、Confluence 也支持 Mermaid 插件可以将 Mermaid 源码直接粘贴无需生成图片。如果文档平台不支持 Mermaid再使用 mermaid-cli 导出 SVG 作为替代。SVG 比 PNG 更适合文档因为放大不模糊占空间更小。7.5 安全与权限边界这是容易被忽略的一点。Mermaid 支持在节点中写入链接也可以在很多渲染环境中引用本地或内网资源。团队内部文档系统如果在浏览器中直接渲染 Mermaid 源码需要留意来源不可信的 Mermaid 代码可能带来的 XSS 或内网探测风险。生产环境的文档系统如果要开放用户自定义 Mermaid 源码建议先经过服务端渲染和安全过滤不要直接让所有用户提交任意 HTML/SVG。对普通团队文档来说代码源文件应放在内部仓库避免把内网链接暴露到外部平台。8. 总结下一次画流程图试试先写代码如果这篇文章只留下一句话那就是下次画流程图时先打开 Mermaid Live Editor把流程写成代码再决定要不要打开图形化编辑器。你会发现逻辑清晰的时候画图真的只是顺手的事。Mermaid 的价值不在于取代所有绘图工具而在于把“思维产物”和“表达工具”解耦。它让流程图、时序图、状态图变成了可以版本管理、可以审查、可以自动化导出的代码资产。对于研发团队这种“用代码管理图表”的方式远比反复拖拽矩形框更符合工程习惯。最后给一个最直接的行动建议本周遇到任何一个需要更新流程图的需求不要直接打开旧图编辑器先新建一个.mmd文件把流程用文字写出来。哪怕第一次语法不够熟练后面只需要对照官方语法手册调整维护成本都会远低于你预期的水平。如果这篇文章对你有帮助可以收藏备用下次改流程图时直接照着示例来。
