Mermaid flowcharts 这类用代码编写流程图的方案最大的价值不是“不用鼠标拖拽”而是改图的时候不用再回到 diagram editor 里反复重绘。只要把图表写成一堆文本后续加节点、改连线、调分组都跟改代码一样保存就能看到新版本。如果你日常要维护架构图、接口时序、状态流转、数据流图并且这些图还经常需要跟着需求变动那么接下来就把这种“不需要重绘”的流程怎么落地拆开讲清楚。1. 为什么说反复重绘才是流程图的真正成本1.1 图形编辑器里的“小改动”其实不省时间用 draw.io、Visio 或在线流程图工具画图第一次拖拽确实很快。节点拖出来连线上拉一下标签双击输入一张图二十分钟内能完成。真正耗时间的是后面的维护。需求一变要加一个节点。看起来只是“加一个框、拉两条线”但实际动作往往是先把附近节点挪开再调整连线绕行再统一对齐最后还要检查有没有漏连。如果这张图有几十个节点改一次至少需要十几分钟改完还要截图放到文档或群里。下一次需求又变这些动作再来一遍。这不是画图能力的问题而是图形编辑器的操作方式决定了“改图”和“重新画图”之间的成本差别不大。一个节点位置变了所有相关节点的坐标都可能要动。对于经常更新的流程图这种成本会一直累积。1.2 代码化流程图带来的三个实打实的好处Mermaid 把流程图变成纯文本描述改图的时候就等于改代码。它带来的第一个好处是 Git diff 可读。旧版本里只有节点 B 连到 C新版本改成 B 连到 Ddiff 里清清楚楚显示这一行变了。图形编辑器做不到这件事最多只能看到“图变了”但很难知道具体哪条线变了。第二个好处是文档同源。Mermaid 代码可以直接嵌在 Markdown 文件里架构文档里的图和文字一起维护。文档更新时图也跟着更新不会出现“文档文字写的是新逻辑图还是三个月前那张”的情况。第三个好处是自动化。Mermaid 文件可以批量渲染可以由脚本生成可以接入持续集成流程。哪怕你一次性维护 20 张流程图只要代码写好了渲染结果就可以统一导出。这一点对技术文档、项目交付、内部知识库特别有用。1.3 它不是替代 Visio而是替代“反复重绘”这种场景Mermaid 不是要打死所有图形编辑器。它真正替代的是那些“逻辑为主、改动频繁、不需要高精度排版”的场景。工具类型优点适合场景不适合场景draw.io / Visio / ProcessOn拖拽直观、样式丰富、排版自由一次性汇报图、精美架构图、复杂网络拓扑需要长期跟随代码仓库维护的图Mermaid文本化、可版本管理、嵌入文档方便流程图、时序图、状态图、ER 图视觉要求高、需要像素级布局的图所以不要被“Mermaid 能画所有图”这句话带偏。正确姿势是把那些经常要改的逻辑图转移到 Mermaid把那些一年到头可能只改一次的展示型大图继续留在图形编辑器里。2. 先跑通环境Live Editor、VSCode 插件和命令行渲染搜索“mermaid 渲染工具”会看到很多选择。实际不需要全装先掌握下面三条链路就够用浏览器在线编辑、VSCode 本地预览、命令行批量导出。2.1 浏览器验证最快Mermaid Live Editor 网页版很多人搜“mermaid live editor 网页版登录入口”其实 Mermaid Live Editor 并不需要传统意义上的登录。它就是一个浏览器编辑器左边写 Mermaid 代码右边实时渲染成图。适合第一次接触 Mermaid 时验证语法、调试节点和连线、尝试新图型。我一般用它做三件事测试一段语法能不能渲染。快速生成一个临时流程图给同事看。把别人发的 Mermaid 代码粘进去检查报错。Live Editor 还支持导出 PNG 和 SVG。就算你不想在本地装任何东西纯用浏览器也能把 Mermaid 用起来。2.2 VSCode 本地预览装一个 mermaid preview 插件日常写技术文档时我更习惯在 VSCode 里工作。VSCode 的 Markdown 预览默认不渲染 Mermaid需要装一个预览插件。搜“vscode mermaid preview 插件”能找到好几个装好后在 Markdown 文件里写 Mermaid 代码块打开预览就能直接看到渲染结果。需要注意一点插件版本和 VSCode 版本、Markdown 预览引擎之间偶尔会有兼容性问题。表现是代码没问题但预览区只显示代码块不显示图。碰到这种情况先看插件是否启用再看是否需要更新 VSCode最后把 VSCode 窗口重新加载一次。很多时候不是代码语法问题而是预览插件没生效。2.3 命令行渲染mermaid-cli 负责批量导出如果只是在单个 Markdown 文件里看一下VSCode 插件就够了。但当你需要把图导出给外部同事、放进 PPT或者批量渲染几十个流程文件时命令行工具会更稳。mermaid 官方提供了一个命令行渲染方案通常通过 npm 生态安装。前提是机器上有 Node.js 环境。因为渲染过程依赖 Chromium 相关的浏览器组件第一次运行可能会比较慢或者在环境里找不到浏览器。这不是 Mermaid 本身的问题而是系统缺少运行依赖。一个典型的单文件渲染命令大概长这样mmdc -i diagram.mmd -o diagram.svg如果需要 PNGmmdc -i diagram.mmd -o diagram.png不同版本的具体参数会有差异。建议先用最简单的单文件命令把链路跑通再去看批量参数。不要一上来就套一个复杂脚本否则报错时你根本分不清是语法问题、依赖问题还是脚本逻辑问题。3. 流程图语法先吃透这些你就能应付 80% 的需求Mermaid 语法本身不复杂但它的官方完整语法手册内容很多。真要照着手册全部学一遍容易劝退。比较合理的做法是先掌握 flowchart 的节点、连线、方向再补子图和样式最后按需学习时序图、状态图等类型。3.1 flowchart 的核心是“节点 连线 方向”先看一个最小的例子flowchart LR A[需求] -- B[设计] B -- C[开发] C -- D[验收]第一行flowchart LR表示这张图是左到右布局。常用的方向有LR从左到右。RL从右到左。TB从上到下。BT从下到上。方向为什么重要因为 Mermaid 是自动布局。你只描述节点之间怎么连不描述坐标。布局方向会直接影响渲染出来好不好读。我自己的经验是大多数业务流程图用 TB 或 LR 就够了不要在一张图里混用太多方向。节点多了以后自动布局会把图拉得很长这时候优先压缩节点数量而不是纠结方向。节点文本支持中文直接用A[需求]这种写法就行。如果文本里有括号、引号等特殊字符记得加引号或者换一种写法否则容易解析失败。箭头符号也值得注意。--是实线箭头---是实线无箭头-.-是虚线箭头是加粗箭头。新手最容易出的问题就是-中间少了一根横线导致整段代码无法渲染。3.2 节点形状、子图和样式该什么时候用节点形状主要用于语义表达。例如A[普通矩形]常规步骤。A(圆角矩形)开始或结束。A{菱形}判断分支。A[(圆柱)]数据库。A[/平行四边形/]输入输出。这些形状在代码里就是字符不同阅读成本很低建议按实际含义使用不要每个步骤都用矩形。子图用subgraph声明适合把一群节点分成一个组flowchart TB subgraph 前端 A[页面] B[交互] end subgraph 后端 C[接口] D[数据库] end A -- C B -- D子图能提升可读性但不要嵌套太多层。我见过有人把子图套三层渲染出来布局间距异常节点乱跳。Mermaid 的自动布局对嵌套子图的容忍度有限一般一层或两层比较稳。样式方面可以使用classDef给节点加颜色、边框等。这个能力适合给重点节点做强调。但要注意Mermaid 的样式功能不等于专业绘图工具别用它做复杂视觉设计。一旦你开始手工调整每一个节点的颜色、位置、字体它就不是“不用重绘”的工具了维护成本会重新涨回去。3.3 时序图和其他常见图型流程图之外Mermaid 里最常用的是时序图。经常有人搜“mermaid 时序图应该怎么画”。其实核心就是声明参与者再写消息传递sequenceDiagram participant 用户 participant 后端 用户-后端: 提交订单 后端--用户: 返回结果这种图特别适合描述接口调用顺序、多服务协作、登录流程等场景。相比 flowchart时序图的排版更固定不需要担心节点乱跑改动的几率也更高是 Mermaid 里很值得优先掌握的类型。其他图型还包括状态图stateDiagram-v2适合描述状态机。甘特图gantt适合描述项目排期。ER 图erDiagram适合描述数据库表关系。用户旅程图journey适合描述用户体验路径。不要一开始就全部学。如果主题还没用到看一遍知道“有这个能力”就行。真正需要的时候再去查对应章节Mermaid 官网语法手册比任何二手教程都完整。4. 从 draw.io、Visio 迁移到 Mermaid不要指望一键转换很多老项目里已经有一堆 draw.io 或者 Visio 画好的流程图。想转到 Mermaid最常见的误区是想着“一键把 drawio 转成 mermaid”。这个想法可以理解但实际落地时要降低预期。4.1 为什么现成的图很难直接变成 Mermaiddraw.io 和 Visio 里的图保存的是节点坐标、连线路径、样式、分组等位置信息。Mermaid 保存的是逻辑关系。这两个模型本身就不对齐。坐标信息在 Mermaid 里没有对应概念因为 Mermaid 是自动布局。连线路径和折线绕行在 Mermaid 里也不受控“从哪个点连接到哪个点”这种细节无法直接转换。样式更是如此draw.io 里一个节点的渐变、阴影、字体大小转换后会丢失或变形。所以现成的 drawio 转 mermaid 工具对简单图可能勉强能用对复杂图基本只能把节点和连线抽出来生成的代码仍然需要大改。4.2 迁移的正确姿势先看逻辑再写代码我建议把迁移过程当成一次“重构”而不是“转换”。步骤如下打开原图把图里所有节点抄成一份清单写清楚每个节点的含义。把所有连线串成一条流程标出分支条件。忽略原图坐标和样式只关心节点的前后关系。用 Mermaid 按逻辑写一遍。渲染后对照原图检查确认没有漏节点、连错线。举例来说画一个用户登录判断流程原图可能用菱形表示“验证是否通过”转换后分支关系仍然要保留flowchart TD A[用户输入账号密码] -- B{验证是否通过} B -- 通过 -- C[进入系统] B -- 不通过 -- D[提示错误]这样写出来的图可能和原图长得不一样但逻辑是对的而且后续改起来很快。迁移的目标不是“长得一样”而是“逻辑可维护”。4.3 AI 辅助写 Mermaid 代码的可行做法现在也可以用生成式 AI 辅助写 Mermaid。你可以把原图的截图、节点关系、或者一段文字描述发给大模型让它生成一份 Mermaid 代码。这个做法能节省不少时间但要注意生成结果必须人工核对千万不要直接复制到正式文档里。我见过不少案例模型把连线漏了一条把判断方向写反了甚至把节点 ID 引用错了。渲染不报错不代表逻辑正确。更稳的做法是让模型生成初稿自己把节点清单和连线路径过一遍再用 Live Editor 渲染确认。确认无误后再提交到仓库。4.4 迁移完成后的验收清单迁移完一张图可以用下面这个清单判断是否成功能不能正常渲染不报语法错误。所有原图关键节点是否都在。每条连线是否与原图逻辑一致尤其是分支条件。节点命名是否可读能否通过 ID 看出业务含义。后续改一条流程时能不能在 5 分钟内定位到对应代码。如果上面任意一项不满足先不要急着迁移下一张图。把问题解决在单图阶段批量迁移才不会出大乱子。5. 让 Mermaid 进入日常工作流文档、批量导出和团队规范当手里只有一两张图时直接用 Live Editor 就够了。但当 Mermaid 真正进入项目文档就会涉及到 Markdown 内嵌、批量渲染和团队协作规范这才是“不用反复重绘”的完整形态。5.1 文档与图同源Markdown 内嵌是最舒服的用法GitHub、GitLab 以及不少内部文档平台都支持在 Markdown 代码块里写 Mermaid 并自动渲染。这意味着你不需要单独维护图片文件流程图就是文档的一部分。比如你写一篇接口设计说明正文里描述请求流程代码块里放一张时序图。后来接口改了正文和时序图一起更新提交一个 PR 就完事。相比原先“改文档后还要打开 draw.io 改图、导出图片、替换图片地址”的流程省掉了大量重复操作。docsify、VuePress、Docusaurus 这类静态站点工具也都有 Mermaid 支持方案。团队知识库如果用 Markdown 体系Mermaid 的嵌入成本很低。5.2 批量渲染写脚本处理多个 .mmd 文件如果项目里有很多独立的 Mermaid 文件可以用命令行工具批量渲染。首先要统一约定每个.mmd文件是一个独立的图不依赖其他文件。然后写一个循环脚本遍历目录里的所有.mmd文件逐个输出成 PNG 或 SVG。一个基本的脚本思路如下for file in diagrams/*.mmd; do mmdc -i $file -o output/$(basename $file .mmd).svg done执行之前建议先手动渲染一个文件确认命令能跑通。批量渲染时最容易出现的问题不是 Mermaid 语法而是输出目录不存在、文件名带特殊字符、某个文件语法错误导致脚本中断。所以脚本里最好加上“失败时输出日志但继续跑下一个文件”的逻辑。我自己的习惯是把所有 Mermaid 源文件放在diagrams目录渲染结果放在output目录文件名和源文件保持一致。这样出了问题能很快定位到是哪个文件导致的。5.3 团队用 Mermaid 要提前定三条规范人数一多如果没有规范Mermaid 代码很快就会变得混乱。建议至少约定三条节点 ID 用有业务含义的英文不要用数字编号。例如A[登录]不如login[登录]可读。一行只写一条连线。不要在一行里堆A -- B -- C虽然能渲染但排查 diff 时很难读。子图嵌套不超过两层。保持布局稳定也保持代码可读。另外如果节点文本包含中文标点、括号、引号要给文本加上引号或者转义。不同版本对特殊字符的容忍度不完全一样规范统一后能少踩很多坑。5.4 版本管理和评审Mermaid 代码进入 Git 仓库后最重要的优势就是可评审。需求变更时PR 里可以清楚看到哪些节点加了、哪条线改了评审人不再需要打开图片反复对比。这个能力在图形编辑器里很难得。draw.io 的源文件虽然也是 XML但大部分人在 review 的时候不会去读 XML。Mermaid 代码本身就是图的结构天然适合 Code Review 场景。6. 常见报错和排查顺序别一上来就怀疑工具Mermaid 用久了真正让人头疼的不是语法难而是出了问题不知道往哪查。下面按我自己踩坑的经验整理了一套排查顺序。6.1 先把问题分类遇到问题先看现象再分类处理。现象常见原因优先检查项整段代码无法渲染语法错误、箭头符号写错、括号不匹配用 Live Editor 单测代码能渲染但布局很乱子图嵌套过深、节点过多、方向设置不合理减少节点、简化子图、换布局方向导出 PNG/SVG 失败渲染依赖缺失、输出目录无权限先跑单文件命令、看命令行日志中文显示为方块环境缺少中文字体给渲染环境安装字体或指定字体配置预览插件不显示图插件未启用、VSCode 版本不兼容重新加载窗口、检查插件日志6.2 语法层面的高频雷区先说箭头。--和-完全不一样。Mermaid 的 flowchart 用的是--少一条横线就直接报错。再说节点文本。文本里出现英文括号时会干扰 Mermaid 解析。比如节点文本写B(处理(待确认))内层括号容易让解析器产生歧义。解决办法是给文本加引号比如B[处理(待确认)]或者换个表达。还有 ID 重复。同一个图里不能有两个节点使用同一个 ID。重复后通常不会直接报错但会出现节点被错误合并、连线指向错误的问题。比较隐蔽。缩进也要注意。虽然 Mermaid 不像 Python 那样强制缩进但subgraph里的节点如果缩进混乱渲染结果会和你预期不一致尤其是一段代码从文档复制到另一个文件时空格和 Tab 混用会带来奇怪的问题。6.3 渲染和导出问题命令行渲染失败时先看是否缺少浏览器运行环境。Mermaid 渲染需要借助 Chromium 相关能力有些服务器环境很干净第一次运行时需要下载或指定浏览器路径。这类问题不是代码问题而是环境问题。如果导出图片时中文变方块大概率是运行环境中没有安装中文字体。本地电脑上可能没问题但放到 CI 服务器上就会暴露。解决方向是提前在环境里安装字体或者在 Mermaid 配置里指定一个可用的中文字体。文件路径也容易踩坑。文件名带空格、带中文、带符号时命令行处理常常出问题。建议批量渲染前统一文件名规则尽量用英文小写、中划线或下划线。6.4 推荐的排查链路我自己排查的顺序固定是先最小化复现。把出问题的代码复制到 Live Editor一点点删除分支找到最小可渲染片段。再看输入格式。检查引号、括号、箭头、缩进确认是不是 Mermaid 语法问题。再看渲染环境。确认预览插件、命令行工具、浏览器依赖是否正常。最后看版本边界。不同版本的 Mermaid 对某些语法支持程度不同旧项目升级后出现渲染变化并不罕见。按这个顺序走一遍大部分问题都能定位。不要一上来就怀疑是 Mermaid 解析不了你的图多数情况是环境或输入格式问题。7. 什么情况下别硬用 Mermaid边界比能力更重要Mermaid 很好用但它不是万能工具。知道什么时候不用它反而能避免很多不必要的折腾。7.1 视觉要求高的图还是用专业绘图工具如果你做的是对外汇报的架构大图要求配色统一、层级分边距准确、视觉冲击力强那 Mermaid 的自动布局很难满足。这种图通常低频修改、展示价值高适合用 draw.io 或 Visio 精细调整。复杂拓扑图、机房网络图、组织架构大图这类有明确位置关系、甚至需要背景底图的场景也不适合硬改成 Mermaid。硬写会花很长时间调整最终效果还不一定好。Mermaid 的定位是“逻辑图”不是“视觉设计图”。你越早接受这个边界用它的时候越顺手。7.2 Mermaid 真正适合的场景清单反过来看以下场景很适合 Mermaid业务流程图节点清晰改动频繁。接口时序图描述请求顺序天然适合文本表达。状态流转图状态机和事件驱动Mermaid 状态图很契合。数据库 ER 图表结构变更时Mermaid 代码和 SQL 变更可以一起提交。项目排期甘特图只要约定好任务格式更新成本很低。这些场景都有一个共同特点内容价值大于排版价值修改频率高需要文档和代码一起维护。7.3 我的使用建议从小到大把单图跑稳再扩展第一次尝试 Mermaid 时不要一上来就把所有旧图全部迁移。先挑一张最常用、改动最频繁的流程图在 Live Editor 里写通再放进 Markdown 文档最后接入命令行批量渲染。这个流程走通后再迁移第二张、第三张。过程中你会形成自己的节点命名习惯、子图使用规范和排查经验。等维护的图多起来后你会明显感觉到改图不再意味着重新拖线、重新对齐、重新导出而只是改几行文本、提交一次代码。这也是这个项目标题里“dont have to redraw in a diagram editor”最有价值的地方。你省下的不是第一次画图的时间而是每次需求变更后被迫重画的那些时间。逻辑图变成代码维护方式才能真正跟得上代码仓库的节奏。