第一次真正意识到这个问题是在一次项目文档翻新的时候。系统模块调整了业务流程的分支变了原来的流程图里三四个节点需要重排两条连线要改走向还有一处分支要拆成两条。我当时的做法和大多数人一样打开绘图编辑器删掉旧图形重新拖控件、对齐、连线、调样式、导出发布。整个过程花了四十分钟而且大部分时间不是在思考业务逻辑而是和图形布局搏斗。Mermaid 最近在 Hacker News 上有一个很简洁的项目标题Mermaid flowcharts you dont have to redraw in a diagram editor。这句话几乎说出了我这两年画流程图最深的感受——流程图本该是代码的产物而不是绘图工具里的手工对象。Mermaid 能让你用一段文本描述流程结构然后自动渲染成图当需求变化时你只需要修改文本重新渲染图表就是新的。但很多人对 Mermaid 的理解还停留在“一个画图工具”或者“一种 Markdown 代码块”这其实是把它的价值看小了。这篇文章我想从“为什么要用文本定义流程图”说起讲清楚 Mermaid 真正解决的问题、上手路径、常见坑以及它适合放到什么场景里用、不适合放到什么场景里用。1. 先搞清楚 Mermaid 真正解决的“重画”问题1.1 传统绘图编辑器为什么会在流程变更时成本很高传统绘图编辑器的最大问题不是画不出漂亮的图而是图一旦画完就变成了一堆“图形对象”的集合。每个节点是独立对象每条连线是独立对象位置、尺寸、样式、对齐关系都是被显式记录下来的。这在初次画图时没问题。真正的问题出现在变更发生时。业务逻辑一变你得做的不只是“改文字”而是找到需要变化的节点移动位置删除或重接连线调整相邻节点避免重叠重新对齐保证视觉一致调整样式保持颜色和形状统一最后导出图片替换到文档里。看起来都是小事但积少成多。很多团队最终选择不修改旧图而是重新画一张新图。这不是懒而是重画往往比调整旧图更快。流程图的本质是表达“流程结构”但传统编辑器把“结构”和“视觉”强行绑在了一起。你想改结构就必须一起改视觉两者之间没有任何抽象层。1.2 Mermaid 的核心变化从“画图”到“维护流程定义”Mermaid 做了一个关键反转它把图表的本质从“图形对象集合”还原成了“结构化描述”。画图时你写这样的文本graph TD A[需求提出] -- B{评审是否通过} B -- 是 -- C[进入开发] B -- 否 -- D[补充需求] D -- AMermaid 解析这段文本自动生成对应的流程图。你看到的是图但你维护的是文本定义。每次渲染都是一次全新的生成所以不存在“上次画错位置”的问题也不存在“手动对齐”的问题。“不用重画”这句话的真正含义不是指 Mermaid 能自动帮你把旧图改成新图而是指你根本不需要去“画”图。你修改的是流程的定义图只是定义的结果。这里我想强调一个判断Mermaid 的核心价值不是“帮你省几分钟画图时间”而是让流程图变成一种可以被版本管理、被 diff、被评审、被复用的资产。一张图片格式的流程图在 Git 里就是一个二进制文件它经历了什么变化你几乎看不出来。但一段 Mermaid 文本你可以用 Git 精确地看到每次改动是新增了一个节点还是改变了方向还是移除了一个分支。这带来的变化是工作流层面的不只是绘图体验层面的。1.3 这个方案适合谁不适合谁Mermaid 适合的是有清晰语义结构的图表。比如业务流程图有节点、分支、跳转时序图有参与者、消息、交互顺序状态图有状态、事件、转换类图、甘特图、饼图等结构化图表。这些图的核心信息是“关系”和“流程”视觉布局只是辅助。Mermaid 能自动处理布局你只需要关注结构本身。Mermaid 不适合的场景也很明确需要精细视觉控制的海报式图表需要自由摆放元素、不遵循规则布局的架构图UI 原型图、线框图需要和设计稿风格完全一致的对外材料。这些问题不是 Mermaid 的 bug而是它的边界。Mermaid 是流程图 DSL不是绘图画布。它的布局算法能做的是自动化布局不是你脑海里想要的那种“手工精调后的完美排版”。所以在开始用它之前先做一个判断你要画的图核心是信息结构还是视觉表达如果是前者Mermaid 会非常顺手如果是后者建议用专业绘图工具别硬适配。2. 从零跑通一个 Mermaid 流程图最小可运行流程2.1 先写第一张图graph TD 的最小闭环Mermaid 的语法上手门槛很低但有几个基本概念需要先理解。我建议第一次使用直接打开在线编辑器不要先装任何本地环境。Mermaid 官方提供了一个在线编辑器 mermaid.live打开就能用不需要登录也不需要下载。左边写代码右边实时渲染非常适合从零验证语法。第一张图用最简单的流程闭环graph TD A[开始] -- B[处理请求] B -- C{是否成功} C -- 是 -- D[返回结果] C -- 否 -- E[记录日志] E -- B拆开来看这五行的含义graph TD表示这是一张从上到下Top Down的流程图A[开始]定义了一个节点节点 id 是 A节点文本是“开始”A[开始] -- B[处理请求]表示从 A 连到 BC{是否成功}表示这是一个菱形判断节点C -- 是 -- D[返回结果]表示从 C 到 D 的连线上带有文字“是”。这里有一个新手容易忽略的点节点的 id 和节点显示文本是分离的。A[开始]里A 是 id用于表示节点的唯一身份“开始”是显示文本用于展示。后续你要用 A 来连线就必须引用 A 这个 id。很多人在复杂图里搞混原因是把 id 写成了中文或者带特殊字符导致后续连线报错。2.2 方向、连线和分支把流程图的基本语法拆开方向关键字有四个TD/TB从上到下BT从下到上LR从左到右RL从右到左。实际使用时我建议先默认用TD或LR。先看整体结构是纵向流程还是横向流程再决定方向。如果节点文本比较长横向容易撑宽页面如果节点很多纵向容易导致图太高。没有绝对最优需要根据阅读场景调整。连线类型是流程图语法里最常用的部分graph LR A[节点A] --- B[节点B] A -- C[节点C] C -.- D[节点D] D E[节点E] E -- 带文字 -- F[节点F]---表示无箭头实线--表示带箭头的实线最常用-.-表示带箭头的虚线通常用于弱关系或异步调用表示粗实线用于强调主路径-- 带文字 --用于给连线加文字说明。分支表达式是流程图中最重要的部分。Mermaid 的判断节点用{}表示它本身只是一个节点真正的分支逻辑靠连线文字来表达graph TD A[收到请求] -- B{参数校验} B -- 通过 -- C[执行逻辑] B -- 不通过 -- D[返回错误]这个结构表达的就是“如果通过执行逻辑如果不通过返回错误”。理解起来不复杂但实际绘制时很多人会把分支逻辑写进节点文本而不是放到连线上比如写“参数校验通过”作为节点文本然后用三条线指向同一目标。这种做法没有语法错误但会让图的语义变得混乱因为阅读者无法快速判断条件和结果之间的对应关系。2.3 用 subgraph 组织复杂流程当流程节点超过十五到二十个时即使语法完全正确自动布局也会开始显得混乱。这时最有效的技巧是用subgraph对节点分组。graph TB subgraph 前置阶段 A[创建任务] B[分配负责人] end subgraph 执行阶段 C[执行任务] D{校验结果} end subgraph 收尾阶段 E[归档] F[发送通知] end A -- B -- C -- D D -- 通过 -- E D -- 不通过 -- C E -- Fsubgraph的作用是让一组节点在视觉上被框在一起表达“这些节点属于同一个逻辑模块”。它不参与流程方向只影响视觉分组。这里有一个很常见的坑Mermaid 对subgraph的缩进不敏感但要求subgraph和end配对。如果你漏写了end整个图表渲染会失败。而且不同版本的 Mermaid 对子图内部布局的处理不完全一致所以当你把代码从在线编辑器复制到本地插件或 Markdown 平台时渲染效果可能略有不同。这属于正常现象不需要慌张关键看语义是否一致。2.4 选择渲染工具在线编辑器、VSCode 插件、Markdown 内嵌Mermaid 的上手路径可以分成三个层级第一层是在线编辑器。mermaid.live 适合验证语法、快速做一次性图表、学习新语法。它自带多种示例模板也支持导出 SVG 和 PNG。如果你只是偶尔画一张流程图用在线编辑器就够了。第二层是VSCode 插件。在 VSCode 的扩展市场搜索 Mermaid能找到不少相关插件比如 Markdown Preview Mermaid Support、Mermaid Preview 等。这类插件的典型工作流是打开一个.md文件在代码块里写 mermaid 语法然后打开侧边预览实时看到图表效果。这种工作流的最大好处是图表和文档放在同一份文件里改起来非常快。第三层是平台内嵌渲染。GitHub、GitLab、很多文档系统都支持在 Markdown 中直接渲染 mermaid 代码块。这意味着你可以在代码仓库里写流程图提交后在网页上直接看到渲染结果团队成员不需要安装任何额外工具只要能看到 Markdown 就能看到图。我给新手的建议是先在在线编辑器里跑通语法再迁移到 VSCode 插件里做日常使用最后根据团队协作需求决定是否嵌入到仓库或文档平台。3. 把 Mermaid 放进真实工作流而不是只用来画一张图3.1 时序图另一个被文本化拯救的场景流程图是 Mermaid 最常用的类型但并不是唯一受益的类型。时序图在项目文档里出现的频率极高而且它在传统绘图工具里的维护体验更糟糕。时序图的核心元素是参与者和消息。编写 Mermaid 时你会发现它天然适合描述“谁在什么时候给谁发了什么消息”sequenceDiagram participant U as 用户 participant A as 前端应用 participant B as 后端服务 participant DB as 数据库 U-A: 提交表单 A-B: 发送请求 B-DB: 执行查询 DB--B: 返回结果 B--A: 返回数据 A--U: 渲染页面participant U as 用户定义参与者并给它起一个显示名-表示同步消息--表示异步返回。时序图文本化的优势比流程图更明显因为时序图的信息结构更严格参与者、消息类型、顺序。你用鼠标画时序图时需要手动拖动生命线、调整消息箭头的位置、保证对齐用 Mermaid 写时序图时顺序本身就是代码的顺序消息类型只是符号差异。维护成本完全不在一个量级。如果你所在的团队经常画时序图我建议你重点看一下 Mermaid 官方文档里的 sequenceDiagram 部分。语法项不多但很实用。3.2 在项目文档和代码仓库里使用 MermaidMermaid 最大的价值是在它成为文档体系的一部分之后。单独画一张图它只是输出物嵌入到文档里它变成了文档的逻辑组件。最常见的做法是在 Markdown 文档里直接写 mermaid 代码块mermaid graph TD A[需求] -- B[设计] B -- C[开发] C -- D[测试] D -- E[发布] GitHub 和 GitLab 都能原生渲染这样的代码块。这意味着你的流程图可以放在 README、架构文档、ADR架构决策记录里每次修改都有历史记录不再需要单独维护一张图片文件。更重要的是Mermaid 文本可以参与代码评审。传统图片格式的流程图评审者只能看整体效果很难知道改动点在哪里。Mermaid 文本则像代码一样出现在 diff 中评审者可以清楚地看到哪条连线被改成了什么。这里有一点要提醒不是所有 Markdown 平台都能渲染 Mermaid。CSDN 等部分博客平台对 mermaid 代码块的支持情况不同如果平台不支持你可能需要把渲染后的图片上传。真正需要优先使用 Mermaid 内嵌的场景是代码仓库和自建文档系统而不是所有博客平台。3.3 用命令行和 CI 把图导出成 SVG/PNG如果 Mermaid 图最终要发布到不支持渲染的平台或者要嵌入到 PDF 和 PPT 里就需要把图导出成图片。Mermaid 提供命令行工具通常通过 mermaid-cli 来使用。mermaid-cli 的基本思路是传入一个.mmd文件工具会启动一个无头浏览器内核把 Mermaid 渲染成 SVG 或 PNG。常见命令类似npx -y mermaid-js/mermaid-cli -i input.mmd -o output.svg这个工具适合放进 CI 流程里。比如你的文档仓库中维护了一批.mmd文件每次提交后自动触发导出生成最新的 PNG再发布到文档站点。这样画图的人只需要维护文本不需要手动导出图片。需要注意几点mermaid-cli 依赖无头浏览器运行环境第一次运行可能需要下载浏览器内核文件。如果你们公司的网络环境受限这一步可能耗时较长或失败导出的 SVG 在字体渲染上和本地打开 mermaid.live 可能略有差异如果你在 CI 里导出大量图片要注意构建时长和资源占用。mermaid-cli 的适用场景是“批量生成”和“自动化发布”不是“临时导出”。如果只是偶尔导出一张图直接在 mermaid.live 里复制导出就行。3.4 drawio 转 Mermaid迁移时需注意的边界现在网上有不少开源工具支持把 drawio 文件转换成 Mermaid 语法这给团队迁移带来了便利。但我建议对此保持谨慎预期。drawio 文件本质上是 XML包含节点、连线、坐标、样式这些信息。Mermaid 是只描述语义结构的 DSL不包含坐标和样式。所以从 drawio 到 Mermaid 的转换通常会丢失节点的精确坐标手动画布布局自定义样式、颜色、形状细节分组和层级信息部分可能通过拆分子图恢复。转换工具能做的是提取节点和连线关系尽量还原成 Mermaid 的节点和连线。但转换后的图往往是自动布局的和你原来的手绘布局不同。所以“转换”更像是“提取语义结构”而不是“完整迁移图片”。如果你打算把已有 drawio 图迁移到 Mermaid我的建议是先问一个问题这些图接下来还要频繁改动吗如果还要频繁改动迁移值得做因为 Mermaid 的维护成本更低。如果这些图已经稳定只是为了从工具 A 搬到工具 B那迁移的收益很有限因为你还要花时间检查转换结果、调整子图、处理丢失的样式。不要把 drawio 转 Mermaid 当成无损迁移工具。转换完成后一定要人工检查一遍节点关系和分支逻辑不要直接信任转换结果。4. 实际使用中最容易踩的坑以及一套排查链路4.1 渲染失败或空白先别急着改代码Mermaid 最常见的错误是渲染区域显示一条语法错误信息或者直接空白。遇到这种情况不要立刻重写代码而是按顺序排查。我的排查链路是看渲染面板的报错信息定位到具体行检查语法关键字是否拼写正确比如graph和TD是否写对检查有没有漏掉end特别是使用subgraph时检查节点文本里是否有未转义的特殊字符比如方括号、括号、引号把代码复制到 mermaid.live 里看是否能正常渲染。如果 mermaid.live 能渲染但你的本地插件不能那问题大概率出在插件版本或渲染环境上而不是代码本身。一个容易被忽略的点是节点文本中尽量不要使用中文括号、引号、分号等全角标点作为语法结构的一部分。Mermaid 对全角符号的解析在不同版本中表现不完全一致最稳妥的做法是文本内容可以用中文但语法符号使用半角。4.2 中文字体和样式问题Mermaid 对中文的支持总体没问题但不同渲染环境的字体表现差异很大。在线编辑器里显示正常导出成 SVG 后在网页上中文出现乱码或替换字体甚至导出工具里中文变成方框都是有可能的。这类问题通常不是 Mermaid 语法的问题而是渲染环境的字体问题。解决方向有几个尝试在样式初始化中指定中文字体使用 SVG 导出时检查 SVG 引用的字体是否在你的目标平台存在如果导出成图片后中文显示异常换个导出环境试试比如用 mermaid-cli 或别的版本。如果在 VSCode 插件里预览时中文正常但导出 PNG 后中文异常优先排查你本机字体的兼容性。4.3 图一复杂就乱布局是 Mermaid 的自然边界当节点数量变多时Mermaid 自动布局的缺陷会被放大。节点太多、连线交叉、分支拥挤最终图会变得难以阅读。这种情况不是你的语法有问题而是图表本身的复杂度超过了自动布局的承受范围。我的经验是当流程图的节点数超过 20 到 25 个时开始考虑拆分图或者使用子图。拆图的原则是按业务模块拆而不是按页面大小拆。比如将“订单处理”拆成“创建订单”“支付流程”“售后流程”三张图每张图保持节点数在 10 个左右可读性会大幅提升。如果业务确实是一个完整流程必须放在一张图里那你要接受 Mermaid 的布局结果不要花大量时间手动调样式。Mermaid 本身不提供精细的坐标控制强行用样式 hack 来解决布局问题会牺牲掉文本化最核心的维护性。4.4 什么时候应该果断放弃 MermaidMermaid 不是万能的。以下几个场景我建议放弃 Mermaid选择传统绘图工具或其他可视化方案需要精细视觉控制比如对外发布的流程图要讲究排版、留白、品牌色Mermaid 的自动布局很难满足自由画布型图表架构图、拓扑图、思维导图如果元素可以任意摆放Mermaid 反而会限制你的表达UI 原型图线框图需要精确的位置和尺寸Mermaid 做不到高交互图表需要点击、缩放、联动、动态数据的图Mermaid 也不合适它更适合静态渲染。判断标准很简单如果图的核心是“信息结构”用 Mermaid如果核心是“视觉呈现”用传统工具。两者是互补关系不是替代关系。5. 把“不用重画”变成团队的长期习惯5.1 一个可复用的四步框架从流程到图资产我在多个项目里总结了一个四步框架用来判断和实现“流程图文本化”第一步定义流程结构。不要急着写代码先在纸上或用文字列出有哪些节点、哪些分支、哪些状态、先后顺序是什么。第二步用最小语法描述。选一个视图类型graph TD、sequenceDiagram 等用最少的语法把流程节点和连线表达出来。这个阶段的目标是“能渲染出一张完整的图”不是“渲染得漂亮”。第三步选择视图类型和分组。当结构跑通后再考虑方向、子图、连线文字和样式。用 subgraph 把模块边界表达清楚。第四步纳入版本管理和评审流程。把 Mermaid 文本放进仓库让团队成员可以通过代码评审来分析流程图改动。这个框架的核心是“先保证语义再优化视觉”。很多人一上来就调样式、改颜色结果语义有问题全部白做。5.2 用代码评审来评审流程图的变化传统图片流程图的评审通常是“看图说话”团队成员打开图片用语言描述“这里分支好像改了那里多了一个节点”。这种评审方式效率低且容易遗漏。Mermaid 文本化后流程图可以像代码一样出现在 Git diff 里。评审者能清楚地看到哪一行新增了节点哪条连线被删除或修改哪个分支条件变了哪个子图被重构了。这带来的好处不只是效率还有责任心。当流程图的变化能精确追溯到提交人和动机时团队会更愿意在修改时写下清晰的 commit message文档质量会随之提高。5.3 我的建议先在小范围验证再逐步扩大最后我想给一个很现实的建议不要试图一次性把团队所有图表都迁移到 Mermaid。这个迁移本身也可能变成一种重画工作。更稳妥的做法是选择一个高频更新、结构清晰的流程图比如核心业务流程图或系统状态图先用 Mermaid 重写它跑一两个迭代周期看看维护成本的变化。用完之后让团队切身体会“改文本、不重画”的差异再决定要不要扩大使用范围。Mermaid 的长期价值不是把画图工具替换掉而是改变你对“图”的看法。图不再是一张静态的图片而是一份可维护、可追踪、可复用的流程定义。它和代码一样可以长期演进。所以回到文章开头那句话Mermaid flowcharts you dont have to redraw in a diagram editor。我更愿意把它理解成一句提醒流程图应该跟着业务流程走而不是跟着鼠标走。当你把流程图的维护成本降到可以忽略不记时团队成员才愿意主动更新它。而一张能被持续更新的流程图远比一张精美但过时的图更有价值。