Mermaid 这门工具我第一次上手是在一次架构评审会上被逼的。当时团队里维护系统拓扑图用的是传统画图软件每次改一个服务节点都要打开源文件、拖拽、重新导出图片、上传到文档库评审的时候还要反复解释这次改了什么、为什么这么连。更崩溃的是不同时期的图画风完全对不上——有的用红色箭头表示调用有的用线条粗细表示流量。直到有一天我把架构图的 Markdown 改完顺手在代码块里写了几行 graph LR 语法一渲染拓扑图直接出来了。那一刻我就知道文档里的哑巴图时代该结束了。Mermaid 不是一款复杂的专业绘图软件它更像一种图表的 Markdown。你只需要用近似自然语言的文本描述节点和连线Mermaid 就能帮你渲染出流程图、时序图、甘特图、状态图、类图等常见图表。它的最大优势在于图表变成纯文本后可以像代码一样做版本管理、代码 Review、差异对比。这篇文章我会从最基础的环境准备讲起结合 mermaid live editor 的使用、常用图表语法、进阶定制方案再到跨平台兼容和实际踩坑记录覆盖从入门到落地的完整链路。适合正在写技术文档的开发者、需要画架构图但不想被设计软件绑架的工程师以及任何想把图表文本化的团队。1. Mermaid 到底是什么从画图格式说起1.1 一个核心认知图和代码本可以是一回事传统的绘图方式里图表是一个成品文件你拿到的是渲染后的像素而不是图背后的结构信息。这带来一个很实际的问题所有对图的修改都必须在源文件里完成但源文件往往只有画图的人手里有。文档团队如果三个人维护一张架构图最后大概率会演变成谁有空谁改改完 Export 一份 new_v2_final.png版本乱成一锅粥。Mermaid 的思路是把图的结构和渲染彻底分离。你在文档里写的是节点、连线和层级关系渲染引擎负责把它变成能看懂的图形。这意味着图表本身就成了一等公民的文本内容可以被 Git 追踪、被评审者逐行 review、被打包进 CI/CD 流程输出成 SVG 或 PNG。这和 Markdown 对文字做的事是完全一样的思路用简单的语法表达结构让机器负责排版和呈现。来看一个最基础的示例一段 Mermaid 代码后续所有示例我都用纯文本的形式展示方便你在支持 Mermaid 的编辑器中直接复制graph LR A[写代码] -- B{测试} B --|通过| C[上线] B --|失败| A这段代码的意思非常直白graph LR表示这是一个从左到右Left to Right布局的流程图A[写代码]定义了一个名为 A 的节点内容是写代码--是连线B{测试}定义了一个菱形节点代表判断|通过|是连线上的文字标签。你不需要学任何图形学知识只要理解节点 连线这两个基本概念就能上手。1.2 Mermaid 解决的痛点版本管理、评审和协作在实际工作中我见过太多团队在文档协作上对图表束手无策图怎么也 Diff 不了、注释也没地方写、图片不放大根本看不清细节。Mermaid 把这些问题全带走了。因为它是文本就会有代码变更记录评审者可以在 MR/PR 里清楚地看到你改了哪条边、哪个节点。我们团队后来直接把 Mermaid 源码和渲染后的图片都放进文档仓库源码保证可修改图片保证任何工具都能看两者互相印证。顺带提一个容易被忽略的价值Mermaid 的图表是矢量渲染的在 Retina 屏幕或不同缩放比例下都不会糊。传统位图在高分屏上的毛边问题在 Mermaid 这里完全不存在。尤其当你把它嵌入在线文档、技术博客或项目 Wiki 时这种清晰度优势会直接提升阅读体验。1.3 谁适合使用 Mermaid这个问题我经常被问到。我的回答是只要你的工作中需要让信息变得结构化都用得上。开发者可以用它画调用链、架构图、ER 图产品经理可以用它画用户流程图、状态转换图项目经理可以用它画甘特图排期运维可以用它画部署拓扑。Mermaid 的语法学习成本低到几乎可以忽略你只需要一个下午就能流畅产出第一张像样的图剩下的时间主要用于熟悉各种图型的表达习惯。2. 环境准备与 Mermaid Live Editor 快速上手2.1 用 mermaid live editor 在浏览器里立刻开始最快体验 Mermaid 的方式就是打开在线编辑器 mermaid.live。我第一次用的时候甚至没看任何教程直接在左侧粘贴网上的示例代码右侧立刻渲染出图形。这个工具的交互设计对新手非常友好左侧是代码编辑区右侧是实时渲染预览左改右变。Live Editor 值得记住的几个点右上角有一个Actions按钮可以把当前图导出为 PNG 或 SVG也可以直接复制 Markdown 代码。它支持配置面板可以切换主题默认、暗色、森林、中性等这些主题设置会自动转换成主题变量写进你的代码里。每个图表都有短链接可以直接分享给同事对方打开后就能看到和你一模一样的代码与渲染结果这个功能在协作评审时非常实用。有一点值得注意在线编辑器渲染依赖的是最新版 Mermaid 引擎它的行为和你的文档系统内置的 Mermaid 版本不一定一致。所以我在实际项目中习惯先在 Live Editor 里调试语法然后根据目标平台GitHub、Typora、自建 Wiki 等的版本做微调。这个版本差异的问题后面详细说它是跨平台兼容里最容易踩的坑。2.2 本地安装 Mermaid CLI把图表渲染交给命令行如果你只是偶尔画一张图在线编辑器完全够用但如果你的图表需要频繁更新、需要批量导出或者想接入自动化流程那就得上 Mermaid CLI官方包名 mermaid-js/mermaid-cli命令行工具叫 mmdc。安装很简单前提是本地有 Node.js 和 npmnpm install -g mermaid-js/mermaid-cli装完就能用命令渲染文件了mmdc -i input.mmd -o output.svg mmdc -i input.mmd -o output.png --width 1600 --background whiteCLI 走的是 Puppeteer 无头浏览器渲染所以最终产物和你打开一个 HTML 页面再截图几乎一致。--width参数控制输出宽度--background控制背景色。这个工具的核心价值在于可脚本化配合脚本可以一次性把文档目录里所有.mmd文件批量渲染成图片这个能力在后续的跨平台方案里会派上大用场。2.3 在编辑器里写 MermaidTypora、VS Code 与 Obsidian日常写作场景下我更推荐在支持 Mermaid 的 Markdown 编辑器里直接写图。Typora 对 Mermaid 的支持很成熟只要在代码块里标注 mermaid 语言渲染就是所见即所得的VS Code 可以通过安装 Markdown Preview Mermaid Support 插件在预览面板里实时看到图形Obsidian 也原生支持 Mermaid 代码块适合做个人知识库和团队笔记。这些编辑器本质上都是调用 Mermaid.js 来渲染的所以你的学习成本是通用的学会语法走遍各种编辑器都不怕。但要记住编辑器的内置 Mermaid 版本很可能相对滞后。比如 Typora 某段时间内置的版本就不支持某些新语法你在 Live Editor 里写得飞起粘到 Typora 却报错。遇到这种情况优先检查文档系统使用的 Mermaid.js 版本而不是怀疑语法写错了。3. Mermaid 语法拆解从流程图到甘特图的常用图表3.1 流程图flowchart最常用也最值得吃透流程图是 Mermaid 的根基也是绝大多数人用得最多的图型。它的核心概念只有两个节点Node和连线Edge。节点语法上方括号代表矩形节点圆括号代表圆角矩形花括号代表菱形判断节点(( ))代表圆形节点[/ 斜角 /]代表平行四边形。连线方向有三种基础写法--是带箭头连线---是不带箭头连线-.-是虚线箭头是加粗箭头-- text --或--|text|都是给连线加文字。一个相对完整的示例flowchart TD A[开始] -- B{是否登录?} B --|是| C[跳转首页] B --|否| D[跳转登录页] D -- E[输入账号密码] E -- F{验证} F --|通过| C F --|失败| E这里的TD表示从上到下布局。flowchart是 Mermaid 8.7 之后推荐的写法早期版本用的是graph两者在大多数场景下兼容但flowchart对子图、方向的语义更清晰。我个人从项目可维护性的角度出发统一建议使用flowchart关键字。流程图里还有一个非常实用的能力子图subgraph。子图可以把相关的节点圈在一个容器里非常适合表达服务边界或模块划分flowchart LR subgraph 前端 A[页面组件] end subgraph 后端 B[API 网关] C[业务服务] end A -- B -- C子图在团队架构图中的应用频率极高。我用它画微服务调用关系时一个子图就是一个服务域整个系统边界一目了然。3.2 时序图sequenceDiagram说清楚消息先后顺序时序图是我画接口交互方案时离不开的工具。它的语法更贴近自然语言基本是谁给谁发了什么消息sequenceDiagram participant U as 用户 participant A as 前端应用 participant B as 后端服务 U-A: 点击登录 A-B: POST /api/login B--A: 返回 token A--U: 登录成功participant声明参与者as可以设置显示别名-是实线箭头--是虚线返回箭头。除了基础消息时序图还支持activate/deactivate来表示生命周期的激活状态用Note left/right of添加备注用alt/else/end表达条件分支用loop/end表达循环逻辑。我画方案时序图时最喜欢的就是alt分支它能把正常流程和异常流程在同一个图里对照呈现评审会上基本不用额外解释。需要注意的是时序图的换行在语法上有讲究太长注释建议拆成多条 Note而不是硬塞一行。3.3 状态图、类图、甘特图、饼图按需选择别过度设计Mermaid 支持的图型远不止流程和时序。我整理了一张表把常用图型的适用场景和核心语法点列出来方便你按需选择图型适用场景核心语法流程图 flowchart业务流程、判断分支、系统架构节点、连线、子图时序图 sequenceDiagram接口调用、消息交互、协议流程参与者、消息、alt/loop状态图 stateDiagram-v2状态机、订单状态流转状态、转换、[*] 初始/结束类图 classDiagram面向对象设计、领域模型类、属性、方法、关系甘特图 gantt项目排期、迭代计划日期区间、任务、里程碑饼图 pie占比统计类目 数值用户旅程图 journey用户体验流程场景阶段、任务、满意度评分比如状态图非常适合表达订单状态流转这种业务规则。下面是一个用状态图描述订单状态的示例stateDiagram-v2 [*] -- 待支付 待支付 -- 已支付: 支付成功 待支付 -- 已取消: 超时取消 已支付 -- 已发货: 商家发货 已发货 -- 已完成: 确认收货 已取消 -- [*] 已完成 -- [*]甘特图也非常实用。它用文本描述任务区间能省掉在项目管理软件里反复拖拽的麻烦。但要注意甘特图的日期格式严格建议统一使用YYYY-MM-DD格式并给每行任务补齐start和end或duration避免解析歧义。3.4 图表编译语法版本差异为什么同一段代码在不同环境表现不同学 Mermaid 过程中最让人困惑的现象就是版本差异。Mermaid 发展很快从 8.x 到 9.x 到 10.x再到当前的 11.x语法和配置项都在不断演进。你可能会遇到graph和flowchart的兼容问题。graph不会报错但有些新特性只能用在flowchart上。状态图从stateDiagram改名为stateDiagram-v2。老的语法已不建议使用。Mermaid 10 引入了 ESM 模块化浏览器引入方式发生了较大变化。Mermaid 11 增强了对甘特图的日期解析也增加了更多主题变量。所以我在团队文档规范中强制要求统一使用某一主版本比如 v11并在仓库里记录版本号。如果发现图在 A 平台能渲染、在 B 平台报错第一反应应该是检查 B 平台的 Mermaid 引擎版本而不是怀疑语法。4. 进阶玩法主题定制、交互与复杂布局4.1 主题定制让所有图表长得像一个团队的产出很多团队的文档图表风格杂乱蓝的、绿的、红的都有看上去不像一个体系。Mermaid 提供了一个很好的方案主题变量。你可以在 Mermaid 代码块开头用%%{init: {...}}%%声明初始化配置也能在渲染时统一传入配置。例如%%{init: {theme: base, themeVariables: {primaryColor: #4F79D4, lineColor: #999999, fontSize: 16px}}}%% graph LR A[支付服务] -- B[订单服务] B -- C[库存服务]theme可以选择default、neutral、dark、forest、base。其中base是最灵活的基础主题配合themeVariables可以精确控制节点颜色、连线颜色、文字大小等。我在团队实践中的做法是把一套主题变量固化成一个公共配置文件所有文档统一加载。这样任何人在任何地方画的图视觉风格都是统一的。如果后续要换品牌色只改一处配置全量文档全变比手工改一堆图片强太多。4.2 交互能力让静态图动起来Mermaid 不只是输出静态图片它渲染到 HTML 里时还支持交互。最常用的是click语法点击节点触发跳转graph LR A[服务 A] -- B[服务 B] click A https://example.com/services/a 查看服务 A 详情click可以链接到一个 URL也可以执行 JavaScript 回调在现代版本中需要显式开启。另外给节点设置title属性可以在悬停时显示 tooltip这比在一张图片里堆满注释放要干净得多。需要注意这个交互能力只有在网页环境中才生效。如果你导出成 PNG 或 SVG 后嵌入到 PDF 或预览窗口里点击跳转就不起作用了。所以在设计文档体系时如果交互很重要优先考虑把 Mermaid 直接渲染进 HTML 页面而不是导出静态图片。4.3 复杂布局与细节控制方向、子图与换行Mermaid 的自动布局在没有干预时通常已经不错但一旦节点一多布局就开始不可控。我平时会用到几个技巧显式控制方向flowchart LR从左到右TD从上到下子图内部也可以单独设置方向。这样你可以在一个整体从上到下的图里让某个子图内部从左到右排布表达内部组件并列的语义。长文本换行直接在节点文案里写br标签。比如A[第一行br第二行]渲染后会自动分行。用%%写注释图一复杂注释就很重要。Mermaid 的注释以%%开头不会被渲染出来。调整输出宽度%%{init: {flowchart: {useMaxWidth: true}}}%%让图自适应容器宽度避免在小窗口下横向滚动。还有一个常见的坑节点文字里包含特殊字符。比如你要写订单数量 100这里的小于号可能干扰语法解析。稳妥做法是给节点文字加引号A[订单数量 100]。同理HTML 实体符号建议写成lt;这类转义形式否则在某些平台渲染会中断。5. 跨平台兼容策略从 GitHub 到自有文档站5.1 为什么同一段 Mermaid 代码在不同平台渲染结果不一样跨平台兼容是 Mermaid 从自己画着玩走向团队协作工具时绕不开的一关。核心矛盾在于不同平台的渲染环境不同。GitHub 有自己内置的 Mermaid 渲染器版本可能滞后于社区最新版GitLab 的 Mermaid 版本和 GitHub 又有差别Typora 用的是内嵌的 Mermaid.js自建 Wiki 系统里可能装了插件甚至根本是旧版本。同一个stateDiagram-v2在一个平台能跑在另一个平台可能直接解析失败。我的经验是采用统一版本 双轨输出策略在文档仓库里锁定一个统一的 Mermaid 版本所有源文件都用这个版本的语法写。对关键图表用 mmdc 渲染成图片并直接提交到仓库。在线平台能渲染就用在线代码块不能渲染就引用图片。源码和渲染图同时存在保证任何工具、任何时间都能看到图。这样做的目的是消除环境依赖图片是静态的永远不会因为平台升级而无法显示。源码是活的想改随时改改完重新渲染即可。5.2 中文字体与编码问题本地正常、线上乱码怎么排跨平台兼容里最隐蔽的问题不是语法而是字体。Mermaid 渲染中文字符时依赖字体族本地电脑可能装了微软雅黑线上 Linux 服务器可能一个中文字体都没有结果就是文字显示成方块或直接消失。特别是用 mmdc 在 CI 里导出图片时这个问题几乎必然踩到。解决方法分场景说明如果是浏览器环境渲染解决方案是确保页面 CSS 里设置了合适的中文字体栈例如font-family: PingFang SC, Microsoft YaHei, Noto Sans CJK SC, sans-serif。如果是用 mmdc 导出 PNG需要保证执行环境的操作系统里有中文字体。Linux 环境可以安装 fonts-noto-cjkapt install -y fonts-noto-cjk然后再执行渲染图片里的中文才不会变方块。文件编码务必使用 UTF-8。如果源码文件是 GBK 编码Mermaid 解析时大概率会在中文字符处报语法错误。各个编辑器的默认编码最好统一改成 UTF-8。5.3 接入 CI/CD用自动化生成图片并发布当文档仓库里的 Mermaid 文件数量变多后手动执行 mmdc 一个个导出就不现实了。更合理的做法是把渲染过程接入 CI。这里给一个 GitHub Actions 的简化流程思路工作流里装上 Node.js安装mermaid-js/mermaid-cli扫描仓库里所有.mmd文件批量导出 SVG/PNG然后把产物推回仓库或发布到 Wiki 站点。这个流程看上去多了一步构建但它带来的好处非常明显只要每次提交文档后自动渲染图片和源码就永远保持同步。不会出现源码改了图还是旧的这种尴尬状况。对跨平台兼容来说这也解决了同一个仓库被多个平台引用、各自渲染不一致的问题——源头只渲染一次输出图片所有平台看到的都是同一张图。5.4 安全配置文档渲染与 XSS 风险Mermaid 功能越强安全就越重要。特别是当文档系统允许用户输入 Mermaid 代码、然后渲染给其他用户看的时候你面对的其实是用户提供的 HTML/SVG这一个信任问题。Mermaid 的click事件回调、HTML 标签渲染等能力如果不加限制可能成为注入通道。官方很早就设计了securityLevel配置项。默认值在 10.x 之后是strict会禁用 HTML 标签渲染和 JavaScript 回调loose模式会放开这些能力。我的建议很简单凡是让用户提交 Mermaid 源码的公共平台一律保持strict模式禁止点击回调。如果确实需要交互应该由平台方自己控制链接的白名单而不是把执行权限下放给普通用户。这是团队自建文档站时最容易被忽略但最不能省的一步。6. 常见问题与排查技巧实录6.1 高频报错速查表现象常见原因解决办法渲染区域显示Syntax error in graph节点或连线语法有误比如括号没闭合、逗号不匹配粘贴到 mermaid live editor看行号定位检查是否用了全角符号中文变成方块执行环境缺少中文字体安装 Noto Sans CJK 字体客户端浏览器检查字体栈导出的图片文字挤在一起节点宽度不足增加--width参数调整节点的文案长度利用br换行在 A 平台正常、B 平台渲染失败平台内置 Mermaid 版本落后统一版本关键图用 mmdc 导出图片特殊字符 导致解析异常语法保留字符冲突甘特图日期错误或任务重叠日期格式不一致统一使用YYYY-MM-DD检查 dateFormat 配置click跳转不生效当前环境不是网页渲染或 securityLevel 为 strict在支持交互的网页环境使用或改为a链接这张表是我在团队内做 Mermaid 培训时整理的基本覆盖了日常 80% 的报错场景。6.2 排查思路不要盲目改语法遇到 Mermaid 渲染异常我建议按这个顺序排查而不是盲目改代码先用 mermaid live editor 跑一遍看报错是否复现。在线编辑器通常给到的报错信息最准确。检查文件编码。用 VS Code 打开源码文件看右下角编码是不是 UTF-8。检查特殊字符。重点看、、、引号优先给节点文本套上引号。检查版本兼容。去官方文档确认你用的语法在当前版本是否已被移除或改名。检查渲染环境配置。比如自建站点的 Mermaid 初始化参数、securityLevel 是否影响了渲染。调试 Mermaid 是一个逐项排除的过程一次只改一个变量不要同时改动多行代码否则根本无法确定是哪个改动解决了问题。6.3 我踩过的坑和沉淀的方法最后分享几个我实际踩过的坑。第一个是接入团队 Wiki 时发现内嵌 Mermaid 版本停留在 8.xstateDiagram-v2完全无法渲染。后来我们把 Wiki 的 Mermaid.js 升级到 v11问题才彻底解决。所以如果团队文档以 Mermaid 为核心表达方式升级文档系统依赖这件事一定别拖。第二个坑是 CI 里导出图片时缺字体。当时在 GitHub Actions 里跑 mmdc导出的架构图里所有中文全变成方块排查了大半天原因就是 runner 上没有中文字体。后来在构建脚本里加了一步安装 fonts-noto-cjk问题解决。从那以后我每次在服务端渲染 Mermaid 都会先检查系统字体。第三个经验是写文档规范。我们在仓库里写了一页《Mermaid 使用约定》规定节点命名用英文驼峰、显示文本用中文、统一使用flowchart而非graph、所有源码文件以.mmd后缀结尾、关键图必须同时提交渲染后的图片。看似刻板但执行下来之后团队文档的可维护性明显提升新人也只需要看这一页约定就能写出风格一致的图。Mermaid 这个东西越用越觉得它像是文档世界的结构表达器官。它不完美遇到布局自由度不够、复杂图渲染性能一般、版本迭代频繁等限制但它在让图表可管理、可评审、可追溯这件事上的价值远远盖过了它的短板。我个人在使用中最大的体会是别追求把每一张图都画得复杂华丽把日常 80% 的图用文本化方式沉淀下来就是最大的效率提升。如果你刚开始尝试建议从一张简单的流程图下手跑到 live editor 里渲染成功一次之后的路会越走越顺。