之前给团队维护一份业务流程图时每次需求调整都要打开图表编辑器手动拖动节点、拉连线、对齐文本框最后还要重新导出图片。改一次图也许只要几分钟但几个月下来文档里的图往往和真实逻辑开始脱节甚至没人愿意再去更新。后来我把流程图全部切换成 Mermaid 源码维护需求变了就改源码再重新渲染一次彻底告别了“每次都要重画一遍”的状态。这篇文章会围绕 Mermaid 流程图主题展开从基础概念、渲染工具、核心语法到完整实战案例和常见排错清单把“用代码维护流程图”这条路完整走一遍。无论你是后端开发者、前端开发者还是经常写技术文档、项目方案的工程师都可以按文章步骤直接上手。1. 背景Mermaid 解决了流程图维护的什么痛点1.1 传统图形编辑器的问题大部分团队在画流程图时首选的是 draw.io、Visio、ProcessOn 这类图形编辑器。它们的特点是所见即所得拖拽节点、连线、调整颜色都很方便。但这类工具在长期维护场景下有几个明显痛点图的存储格式通常是二进制文件或复杂 XML放进 Git 仓库后很难看出这次改动到底改了哪个节点。多人协作时如果两个人同时打开同一个文件编辑很容易产生冲突。图片导出后如果需求变化原文件没保存好就只能重新画一张。图形中的文本和样式混在一起批量修改、全局搜索都不方便。这些问题在小文档中不明显但当流程图成为长期维护的技术资产后就会频繁出现“图过期了”“图文件找不到了”“改了代码但忘了改图”等情况。1.2 Mermaid 是什么Mermaid 是一个基于 JavaScript 的图表生成工具它允许你用类似 Markdown 的纯文本语法定义图表然后由工具渲染成 SVG 或 PNG。流程图、时序图、状态图、甘特图、类图等都可以通过文本生成。它的核心思路是图只是一个“渲染结果”真正的源文件是文本代码。所以当业务逻辑变化时你只需要修改文本中对应的节点或连线然后触发重新渲染即可。这也是标题里 “Mermaid flowcharts you dont have to redraw in a diagram editor” 想表达的你不需要再打开图形编辑器去重绘改代码就够了。1.3 为什么开发团队应该关注它Mermaid 非常适合嵌入到 Markdown 文档、GitHub README、GitLab Wiki、企业内部知识库中。开发者可以直接在文档里写一小段 Mermaid 源码渲染引擎自动生成图形。这样文档和代码在同一个仓库、同一个变更记录里图的更新变成代码更新的一部分大大降低了维护成本。对于技术博主和文档维护者来说Mermaid 还有一个额外好处它天然支持版本控制。每次修改都能通过 Git diff 看到是哪个节点、哪条连线发生了变化这是传统图形编辑器很难做到的。2. 环境准备三种常用的 Mermaid 渲染方式Mermaid 本身是纯文本语法所以环境准备的核心就是“找一种方式把它渲染成图”。这里介绍三种常见方式你可以根据自己的场景选择。2.1 Mermaid Live Editor 在线网页版如果你只是临时画一张图或者想快速验证语法可以直接使用 Mermaid 官方提供的在线编辑器 Mermaid Live Editor。这个过程不需要安装任何软件也不需要注册登录打开页面就能写代码。左侧输入 Mermaid 源码右侧实时预览渲染结果。我一般把它当作语法验证工具先在 Live Editor 里调好图再粘贴到项目文档中。需要注意的是网页版编辑器的版本更新比较快而且它依赖浏览器环境。如果公司内网无法访问外部网站可以使用内网部署版或者改用本地 VS Code 插件。2.2 VS Code Markdown Preview Mermaid Support如果你像大多数人一样使用 VS Code 写 Markdown可以在扩展市场搜索 Mermaid 相关插件例如 Markdown Preview Mermaid Support。安装后在 Markdown 文档中写入 Mermaid 源码块打开预览就可以直接看到渲染后的图形。这种方式适合日常文档维护优点是文档源码和图形放在一起修改即时预览。不依赖外部服务适合内网开发环境。支持 Markdown 中嵌入 Mermaid 代码块语法清晰。安装扩展后可能需要重载 VS Code 窗口。如果预览没有生效检查一下 Markdown 代码块的语言类型是否被识别为mermaid。2.3 Mermaid CLI 命令行渲染如果你的项目有自动化构建需求比如文档站点自动导出图片、CI 流程中自动生成流程图可以使用 Mermaid 官方命令行工具。Mermaid CLI 基于 Node.js可以在安装 Node.js 后通过 npm 安装。安装命令如下npm install -g mermaid-js/mermaid-cli安装完成后使用mmdc命令将.mmd文件渲染成 PNG 或 SVGmmdc -i input.mmd -o output.svg mmdc -i input.mmd -o output.png -b white其中-i指定输入文件-o指定输出文件-b可以指定背景色。Mermaid CLI 实际会依赖 Chromium 等浏览器内核来做渲染所以有些环境需要额外安装系统依赖。如果遇到启动失败不要慌后面常见问题章节会提到处理思路。版本方面Mermaid 自身迭代较快v10、v11 之间的语法大体兼容但个别样式和配置项有差异。本文示例以常见版本为准建议你以当前使用的工具内联版本对应的官方文档为准。3. Mermaid 流程图核心语法拆解3.1 图定义与方向Mermaid 流程图使用graph关键字开头后面跟方向标识。常见方向有TD/TB从上到下。BT从下到上。LR从左到右。RL从右到左。最小示例graph TD A[开始] -- B[结束]其中A[开始]定义了一个节点节点 ID 是A显示文本是“开始”。--表示从 A 到 B 的有向连线。方向的选择取决于图的内容。如果业务流程是自上而下的用TD如果分支较多或者场景适合横向排列用LR。需要说明的是Mermaid 会自动完成节点定位你不需要关心具体坐标只需要说明节点关系和方向。3.2 节点与连线节点形状Mermaid 支持多种节点形状不同形状对应不同语义graph TD A[普通矩形] B(圆角矩形) C{菱形判断} D[(圆柱/数据库)] E[[子程序]] F[/平行四边形/]其中矩形和菱形最常用。矩形一般表示一个处理步骤菱形表示判断分支。连线类型除了--之外Mermaid 还支持其他连线类型graph LR A[节点A] -- B[节点B] C[节点C] --- D[节点D] E[节点E] -.- F[节点F] G[节点G] H[节点H]--带箭头实线。---不带箭头实线。-.-带箭头虚线。带箭头粗线。连线上可以加文本标签写法如下graph TD A[用户] --|输入账号| B[登录校验] B --|校验通过| C[进入首页] B --|校验失败| D[提示错误]标签文本写在|中间渲染后会显示在连线旁边。这个能力非常适合表达分支条件。3.3 子图与节点 ID 规范当流程比较复杂时可以使用subgraph将相关节点分组子图可以有自己的标题graph TD subgraph 用户端 A[提交订单] B[在线支付] end subgraph 服务端 C[订单校验] D[库存扣减] end A -- C B -- D子图本身不影响节点的连线关系它更多是视觉上的分组。需要注意的是子图布局由渲染引擎自动完成有时子图之间的顺序不会完全按照源码顺序排布这是正常现象不要试图通过调整源码顺序来强制控制像素级位置。节点 ID 建议使用有意义的英文命名而不是简单用 A、B、C。虽然语法上允许但到后期维护时VRIFY_ORDER比A更容易理解graph TD USER_INPUT[用户输入] -- VALIDATE[参数校验] VALIDATE -- SAVE[保存订单]这样在 Git diff 中我们一眼就能看出改动影响的是哪一步。3.4 注释、特殊字符与中文Mermaid 源码支持注释注释以%%开头graph TD %% 这是一个示例注释 A[开始] -- B[结束]如果节点文本中包含括号、引号等特殊字符需要使用引号包裹整个文本避免被解析成特殊语法graph TD A[订单(已完成)] -- B[状态: 已支付]中文本身可以直接写在节点文本中Mermaid 支持 UTF-8 字符集。但如果你在 CLI 渲染时出现中文乱码通常是渲染环境缺少中文字体而不是语法问题。4. 实战案例用 Mermaid 维护一份订单流程图下面我们用一个典型的订单处理流程完整演示“用代码定义流程图—渲染—修改—再渲染”的过程。4.1 业务需求假设系统需要实现订单创建流程用户提交订单。系统校验库存。库存充足则创建订单并支付。库存不足则提示用户。支付成功后通知用户。这个流程如果用图形编辑器画需求一变就得手动拖拽如果用 Mermaid只需要维护一段文本。4.2 编写 Mermaid 源码新建文件order-flow.mmd内容如下graph TD START[用户提交订单] -- STOCK_CHECK{库存是否充足} STOCK_CHECK -- 是 -- ORDER_CREATE[创建订单] ORDER_CREATE -- PAY[发起支付] PAY -- PAY_SUCCESS{支付成功?} PAY_SUCCESS -- 是 -- NOTIFY[通知用户] PAY_SUCCESS -- 否 -- CANCEL[取消订单] STOCK_CHECK -- 否 -- STOCK_FAIL[提示库存不足]这段代码中STOCK_CHECK{库存是否充足}是菱形判断节点。-- 是 --表示判断结果为“是”时走某条分支。每个节点 ID 都用语义化英文命名文本使用中文便于阅读。4.3 嵌入文档或命令行渲染如果你在 VS Code 中维护 Markdown可以直接把源码放入 Markdown 文档# 订单流程图 mermaid graph TD START[用户提交订单] -- STOCK_CHECK{库存是否充足} STOCK_CHECK -- 是 -- ORDER_CREATE[创建订单] ORDER_CREATE -- PAY[发起支付] PAY -- PAY_SUCCESS{支付成功?} PAY_SUCCESS -- 是 -- NOTIFY[通知用户] PAY_SUCCESS -- 否 -- CANCEL[取消订单] STOCK_CHECK -- 否 -- STOCK_FAIL[提示库存不足] 考虑到本文排版限制文章中的代码块用普通文本展示。你在实际使用时把语言标记设置为mermaid渲染插件会自动识别并渲染成图。如果项目需要独立图片文件可以用命令行渲染mmdc -i order-flow.mmd -o order-flow.png -b white渲染完成后你会得到一张从上到下的订单流程图菱形节点会自动布局判断分支会显示“是”“否”标签。4.4 需求变更时的增量维护假设业务新增一个需求支付成功前需要调用风控接口。这时你只需要在源码中增加一个节点并修改连线graph TD START[用户提交订单] -- STOCK_CHECK{库存是否充足} STOCK_CHECK -- 是 -- ORDER_CREATE[创建订单] ORDER_CREATE -- RISK_CHECK[风控校验] RISK_CHECK -- PAY[发起支付] PAY -- PAY_SUCCESS{支付成功?} PAY_SUCCESS -- 是 -- NOTIFY[通知用户] PAY_SUCCESS -- 否 -- CANCEL[取消订单] STOCK_CHECK -- 否 -- STOCK_FAIL[提示库存不足]注意我们只改动了一行连线和插入了一个节点。如果用图形编辑器你可能需要先打开文件、找到正确的画布位置、拖入新节点、手动连线、再调整布局。而使用 Mermaid从修改源码到重新渲染只需要几十秒这就是“不用重绘”的核心价值。4.5 预期效果与验证方式在 Mermaid Live Editor 中粘贴源码右侧会实时显示流程图。在 VS Code Markdown 预览中代码块渲染为图形。在命令行使用mmdc导出图片文件可直接用于项目文档。验证时重点检查分支标签是否清晰、节点文本是否完整、方向是否符合阅读习惯。5. 为什么不用“重绘”与图形编辑器对比5.1 核心区别Mermaid 和传统图形编辑器最大的区别在于“编辑对象”不同。图形编辑器编辑的是图形对象你需要选择、拖动、对齐Mermaid 编辑的是文本文本即代码代码即源文件。对比来看维度图形编辑器draw.io / VisioMermaid修改方式拖拽节点、调整连线修改文本源码版本管理文件常为二进制或压缩 XML纯文本Git diff 清晰团队协作同时编辑容易冲突可通过 Git 正常合并批量生成很难可以由脚本生成源码嵌入文档需要导出图片直接嵌入 Markdown学习成本拖拽低门槛需要学习少量语法5.2 Mermaid 的适用边界Mermaid 并不是要完全替代所有图形编辑器。对于以下场景传统图形编辑器仍然有优势需要像素级控制布局比如产品原型图、UI 设计稿。图形非常复杂节点超过 50 个布局调整比较困难。需要在图上做精细的视觉美化、品牌配色。Mermaid 更适合的是“逻辑表达型图表”业务流程、架构流程、时序交互、状态转换这类信息量大于视觉表现力的场景。技术文档、代码注释、团队 Wiki 是它最合适的土壤。6. 常见问题与排查思路6.1 常见错误速查表问题现象常见原因解决思路图表不渲染或白屏语法错误或渲染版本过旧粘贴到 Mermaid Live Editor 验证语法中文显示为方块渲染环境缺少中文字体检查系统字体配置支持中文的字体节点文本含括号报错括号被解析为语法符号使用引号包裹文本如 A[订单(已完成)]子图顺序和预期不一致subgraph 不严格约束布局坐标拆分子图或接受引擎自动布局分支线方向错乱节点 ID 冲突或连线定义重复使用语义化 ID检查每一条连线CLI 导出失败Chromium 依赖未安装检查 puppeteer/Chromium 依赖必要时用 Docker 镜像Markdown 预览不显示代码块语言标记不是 mermaid确认代码块使用 mermaid6.2 排查流程如果渲染结果和预期不符建议按以下顺序排查先把源码复制到 Mermaid Live Editor确认语法本身是否正确。再检查环境配置。VS Code 插件是否安装代码块语言标记是否为mermaid。注意特殊字符。节点文本一旦包含[]、()、{}等字符第一时间想到用引号包裹。查看错误提示。Live Editor 会在出错时给出具体行列信息比如 Unexpected token这通常能定位到具体语法位置。6.3 关于“drawio 转 Mermaid”搜索热词中经常出现“drawio 转 Mermaid”。实际上draw.io 的drawio格式是基于 XML 的结构化文件理论上可以通过脚本解析为 Mermaid 源码但因为两种工具的布局模型差异很大转换结果一般只能保留节点和连线关系无法保留坐标和样式。如果你的旧图是用 draw.io 画的建议把旧图当作参考手工将节点关系改写成 Mermaid 源码。这本身是一次流程梳理的过程通常不会花太多时间。7. 最佳实践与工程建议7.1 目录与命名规范在团队项目中建议把所有 Mermaid 源码集中放在一个目录下docs/ ├── README.md └── diagrams/ ├── order-flow.mmd ├── login-flow.mmd └── deploy-flow.mmd这样做的好处是每个图形源码都有独立文件可以和渲染出的图片放在一起Git 提交时源码和图片一起更新评审者可以通过 diff 看到图形变更。节点 ID 统一使用大写英文加下划线文本使用中文或项目统一语言。这样既保留源码可读性又避免中英文混排在代码中造成阅读障碍。7.2 自动化渲染文档图如果项目使用 CI/CD可以在文档构建流程中加入 Mermaid CLI 渲染步骤。比如在package.json中{ scripts: { docs:diagrams: mmdc -i docs/diagrams/*.mmd -o docs/images/ } }那么每次文档更新时运行npm run docs:diagrams就会自动把目录下所有.mmd文件渲染成图片。这样团队中不熟悉 Mermaid 的人也能直接查看图片而不必首先安装插件。7.3 安全边界如果你在 Web 服务端渲染用户上传的 Mermaid 源码需要特别注意安全风险。Mermaid 的渲染过程会执行 JavaScript恶意源码有可能触发脚本注入。官方在较新版本中引入了一些安全防护机制但更稳妥的做法是不要让服务端直接渲染不可信的 Mermaid 源码。如果必须渲染使用隔离环境比如无头浏览器容器。对上传内容做长度、节点数量限制防止资源被耗尽。渲染结果不要直接嵌入到高风险页面优先输出为图片再部署。7.4 控制单图复杂度一个流程图的建议规模在 20 到 30 个节点以内超过这个数量时阅读体验会明显下降。遇到大流程应该先考虑拆分子图再考虑拆分文档。Mermaid 的subgraph可以分组但子图过多时布局引擎也未必能给出理想效果。8. 总结与下一步学习方向本文从“为什么不想重绘流程图”这个痛点出发介绍了 Mermaid 流程图的基本概念、常见渲染工具、核心语法和一个订单流程实战案例同时对比了它与传统图形编辑器的差异给出了常见问题排查思路和工程实践建议。读完你应该已经掌握使用 Mermaid Live Editor、VS Code 插件、Mermaid CLI 三种方式渲染流程图。使用graph、节点、连线、子图、注释等核心语法描述业务流程。通过 Git 维护流程图源码实现“改代码而不是重绘”的维护方式。在团队文档建设中引入 Mermaid 的最佳实践和注意事项。下一步可以继续学习 Mermaid 的时序图sequenceDiagram、状态图stateDiagram、甘特图gantt这些语法和流程图同属一套文本描述体系。实际项目中优先把那些经常变更的架构图、流程图迁移到 Mermaid你会直观感受到文档更新效率的提升。建议今天就尝试把你手头最常改动的一张业务流程图改写成 Mermaid 源码提交到仓库里体验一次“只改文本、不动画布”的维护方式。