最近整理团队知识库，我又把Mermaid从头到尾折腾了一遍。起因很简单：文档里想放一张流程图，又不想为了改一个箭头重新打开Visio拖半天。试了一圈，发现用mermaid代码写图是最顺手的，流程图、时序图、甘特图、柱状图都能写，改起来就是改几行文本，扔进Git还能看历史。为了让后来的人少走点弯路，我把这份简记留在博客里。内容主要分成四块：Mermaid是什么、环境与第一个图、核心语法速查、mermaid柱状图的写法，以及我实际踩过的坑。顺便说一句，网上如果看到“Mermaid破解软件下载”，直接绕开，这东西本身开源免费，压根不需要破解。

1. 先搞明白Mermaid是什么，以及为什么值得记一份简记

1.1 一个用文本画图的轻量工具

Mermaid不是某个需要破解安装包的商业软件，而是一个基于JavaScript的开源图表库。它的工作方式非常像Markdown：你写一段结构化的文本，它读完后自动排版，生成一张清晰的矢量图。很多人第一次接触时会习惯性去找图形界面，但真正用起来就会发现，文本描述图的优势是图形拖拽工具给不了的：图里的每一个节点、每一条连线和逻辑分支都清清楚楚写在代码里，想改哪儿就改哪儿，不用对着画布反复对齐。

我日常写技术方案，最常用的场景是这样的：需求评审前需要画一张“用户从登录到下单”的流程图。用传统画图工具，我得拖框、画箭头、调布局，改一次逻辑要重复操作很久。用Mermaid的话，直接在Markdown里写一段graph TD，一个可维护的流程图就出来了。等于是把“画图”这件事从设计工作变成了文字工作，版本管理、团队协作、文档存档都轻松很多。

Mermaid支持的类型也覆盖了日常文档的大多数需求：流程图（flowchart）、时序图（sequenceDiagram）、类图（classDiagram）、状态图（stateDiagram）、甘特图（gantt）、饼图（pie），从10.3版本开始还支持XYChart，也就是柱状图、折线图这类统计图。所以说“mermaid代码”能干什么，不只是画框架图，它完全能承担一部分数据可视化的任务。

1.2 适合谁用，以及和同类工具怎么取舍

如果你平时的工作涉及写文档、画业务流程、做系统设计说明，或者你需要在知库、博客、项目文档里插入图表，Mermaid是性价比很高的一类方案。它不像PlantUML那样需要额外装Java环境，也不像draw.io那样必须依赖桌面端或网页端编辑器。Mermaid只要你的文档平台支持渲染，或者你本地装了对应插件，就能直接工作。

我整理过一张工具对比表，帮自己在不同场景下做选择：

从这个表就能看出，Mermaid的优势是“快”和“版本友好”。它适合记录逻辑，而不是做精美的视觉设计。比如几个人一起维护技术文档，别人改了一张图，你用git diff能直接看到是哪个节点变了，这在传统画图工具里几乎做不到。所以我的建议是：逻辑类图表优先用Mermaid，视觉展示类图表再考虑draw.io这类工具。搞清楚边界，才不会在工具选型上反复踩坑。

2. 从零跑通Mermaid代码：安装、第一个图和破解软件避坑

2.1 本地环境怎么搭，其实可以很轻量

我第一次上手时以为要装一堆依赖，实际折腾下来发现，最省事的入门方式是直接用浏览器打开官方在线编辑器mermaid.live。左边写代码，右边实时出图，还能一键导出PNG或SVG，适合临时画几个图。在线编辑器甚至内置了示例模板，对着改数据就行，基本不需要看文档。

如果你想在本地文档里用，比较常见的路线是三选一。第一，VS Code装一个名为“Markdown Preview Mermaid Support”的插件，写完代码直接按预览就能看到图。第二，用Typora这类原生支持Mermaid的Markdown编辑器，设置一下主题和配色，体验很顺滑。第三，如果图要嵌到自己的网站或内部系统里，可以通过CDN把Mermaid引入页面，然后初始化渲染。

我通常在内部系统里用的是第三种，因为要把用户上传的文本动态渲染成图，不能依赖桌面软件。最简单的引入方式是这样：

<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script> <script> mermaid.initialize({ startOnLoad: true }); </script> <pre class="mermaid"> graph TD A[开始] --> B[结束] </pre>

这里重点理解一下：pre标签加上mermaid类，页面加载后Mermaid会自动扫描整个文档，把里面符合语法规则的内容替换成渲染好的图。这种方式的优点是没有构建步骤，适合快速验证。如果是正式项目，我还是建议通过npm安装包的形式引入，方便做版本锁定和构建优化。

2.2 第一个流程图：先跑通最小闭环

不管用什么环境，第一个图建议从最简单的流程图开始。我经常用这个例子带身边的人入门：

graph TD A[收集需求] --> B{优先级排序} B -->|高优| C[进入迭代] B -->|低优| D[放入Backlog]

这段mermaid代码是什么意思？第一行graph TD表示这是一张自上而下排布的流程图，TD是Top Down的缩写，也可以写LR变成从左到右。接下来每一行定义一条关系：A[收集需求]生成一个矩形节点，节点ID是A，显示文本是“收集需求”；B{优先级排序}生成一个菱形判断节点；-->是实线箭头，箭头上的|高优|就是连线标签。渲染出来的效果就是：需求先进入“收集需求”节点，然后到“优先级排序”判断，高优进入迭代，低优放入Backlog。

你可能会问，为什么节点前要加A、B这种ID？因为后续可能有其他节点需要引用它。比如你想加一条“高优任务完成后回归Backlog”的线，就只需要写C --> D，不需要重复描述节点内容。节点ID是整个图里的唯一标识，文本只是展示内容，两者分离让修改只动一个地方，其他关联会自动生效。这个理念贯穿Mermaid所有图类型，理解它之后学别的图会很快。

2.3 网上那些“Mermaid破解版”是怎么回事

这里必须单独说一件事：我在整理热词的时候看到不少搜索记录是“Mermaid破解版”“Mermaid破解软件下载”，这完全是一个误区。Mermaid是MIT开源协议的免费项目，源代码公开在GitHub上，任何人都可以下载、使用、商用，压根不存在“需要破解”的功能。所谓“破解版下载站”，要么是拿官方开源源码二次打包，要么就是捆绑下载器、广告弹窗和恶意脚本，专门找不熟悉开源软件的用户下手。

我自己就见过有人下载了一个“绿色免安装版”Mermaid，结果双击运行后弹出一堆广告，还往系统目录里塞了不明文件。实际上，Mermaid根本不需要安装什么“软件”，你访问mermaid.live在线编辑器，或者用npm安装目录依赖，就已经是官方完整版本了。所以遇到任何“破解版”资源，正确做法是直接关闭页面，从官方渠道获取。这也算是我写这篇简记时最想强调的安全提醒：工具本身免费，但不要因为“免费”两个字放松警惕。

3. 核心语法速查：流程图、时序图、甘特图，一次养成记

3.1 流程图：节点形状与连线规则

流程图是Mermaid里最基础也最常用的图，很多人一上来就卡在节点形状上，其实语法就几条。矩形节点用A[文字]，适合表示普通步骤；圆角矩形用A(文字)，常用于开始或结束；菱形用A{文字}，表示判断分支；圆形用A((文字))，一般用来表示连接点或特殊状态。实战里我最常用的是矩形和菱形，真的需要表达子流程时，可以用subgraph把一组节点框起来。

连线规则比节点形状更需要记牢。A --> B是带箭头的实线，表示流程方向；A --- B是不带箭头的实线，适合关联关系；A -.-> B是虚线箭头，常用于弱依赖或“可选路径”；A ==> B是粗箭头，适合重点强调。如果要在线上写文字，可以用A -->|文案| B，或者A-- 文案 -->B，两种写法结果一样，我个人更习惯第一种，因为它把文字和箭头收集在一个语法块里，阅读时不容易漏。

看一个综合例子，包含子图和不同连线方式：

graph LR subgraph 用户端 A[登录] B[浏览商品] end subgraph 服务端 C[校验Token] D[返回数据] end A --> C B -.-> D C ==> D

这段代码会生成一个从左到右的图，两个子图把用户端和服务端分开，登录后走实线箭头到校验Token，浏览商品走虚线到返回数据，最后校验通过后用粗箭头表示强依赖。子图在画系统模块边界时特别有用，它本质上不是容器，而是一个视觉分组，能明显提升图的可读性。

3.2 时序图：记录消息流转顺序

如果需要表达多个对象之间的消息顺序，时序图比流程图合适。Mermaid的时序图语法也很口语化。sequenceDiagram作为第一行，然后用participant声明参与对象，接着按时间顺序写消息，消息方向通过箭头符号控制。这里最关键的是区分自己发出的消息和响应消息：实线箭头表示同步调用，虚线箭头表示异步返回，椭圆箭头或x箭头还表示消息丢失或异常，不过最常用的还是实线和虚线。

我举个例子，用户登录接口的时序可以写成这样：

sequenceDiagram participant U as 用户 participant S as 服务端 U->>S: 发起登录请求 activate S S-->>U: 返回Token deactivate S

这里activate S表示服务端进入处理状态，在时序图的垂直生命线上会显示一个矩形条，deactivate S表示处理结束。这个过程看起来简单，但团队评审时非常直观：新同事一看就知道第一步是用户调服务端，第二步是服务端返回，而且生命线说明了处理在哪一端持续。写消息内容时，如果文字里包含冒号或括号，尽量用英文双引号包起来，否则在某些版本里会被错误解析。

3.3 甘特图与饼图：项目管理也能可视化

甘特图的mermaid代码和命令式很像，核心是把任务拆成“已开始”“已完成”“未来任务”三档。下面是一个我排周计划的例子：

gantt title 项目排期 dateFormat YYYY-MM-DD section 开发阶段 需求评审 : done, r1, 2024-03-01, 3d 编码开发 : active, c1, 2024-03-04, 2024-03-08 联调测试 : t1, 2024-03-09, 3d

第一行gantt声明类型；dateFormat定义日期格式，默认是YYYY-MM-DD；section表示分组；任务名后面的: done或: active是状态标识，分别代表已完成和进行中，不写状态则默认为未开始；状态后面可以加一个任务ID、开始日期、持续时长，也可以写起止两个日期。我自己最常用的写法是“开始日期+持续天数”，因为排期时改持续时间更容易。

饼图的语法更简单。只需要声明pie，然后写“名称: 数值”即可。比如：

pie title 本周时间占比 "开发" : 45 "会议" : 20 "学习" : 25 "休息" : 10

它会自动计算比例并生成带图例的饼图。做周报时用这种图展示时间分布，比手动做Excel图表快很多。不过饼图的比例是相对大小，如果数据本身不构成整体，也不建议硬套这个图，该用柱状图时就得用柱状图。

4. 柱状图到底怎么写？mermaid 柱状图的正确姿势

4.1 官方原生支持，不需要额外插件

很多人搜“mermaid 柱状图”时会发现网上教程不多，甚至有人用拼接图片的方式硬做，其实Mermaid官方早就支持了。从10.3版本开始，Mermaid引入了XYChart，用xychart-beta作为起始关键字，配合x轴、y轴和数据结构，可以原生渲染柱状图、折线图，甚至可以把柱状图和折线图叠加在一张图里。这个能力对版本有硬性要求：如果你用很老的Mermaid版本，或者在线编辑器没有升级，写再标准的代码也是白搭，容易误以为语法写错了。

我在本地验证时最常用的是官方mermaid.live，左上角可以切换Mermaid版本，默认版本通常已经是最新的。如果在自己的站点里用Mermaid，建议安装mermaid@10.3.0以上版本，最好直接锁定到更新的稳定版。因为XYChart的语法还在持续完善，不同小版本的容错度有细微差别，锁定版本能避免同一份代码在不同页面渲染结果不一致的问题。

4.2 一个可直接复制的柱状图模板

写柱状图的核心是四个部分：图表类型、标题、x轴类目、y轴范围、柱状数据。这里给出一个最常用的模板，我每次做月度数据展示都会抄它：

xychart-beta title "月度销售额" x-axis ["1月", "2月", "3月", "4月"] y-axis "销售额(万元)" 0 --> 100 bar [30, 55, 42, 78]

xychart-beta声明这是一个XYChart；x-axis后面的数组是柱状图的类别标签，对应每个柱子下方的中文或英文名称；y-axis后面先写坐标轴的单位说明，再接0 --> 100表示数值范围从0到100；bar后面是柱子值列表，与x轴数组按顺序一一对应。这段代码渲染后，你会得到一张干净的双轴柱状图，不需要额外配置颜色、间距或网格线，默认样式已经足够用于日常报告。

如果柱子太多，或者想调整方向，可以加一个horizontal关键字，让柱子变成横向条形图：

xychart-beta horizontal title "编程语言使用人数" x-axis ["Python", "JavaScript", "Go", "Rust"] y-axis "人数" 0 --> 100 bar [80, 70, 45, 20]

横向图在类目名较长时更不容易被截断。另外，想在同一张图里看趋势线和柱状对比，可以在bar后面再加上一行line，Mermaid会把柱状图与折线图融合显示。例如：

xychart-beta title "月度销售额与目标值" x-axis ["1月", "2月", "3月", "4月"] y-axis "万元" 0 --> 120 bar [30, 55, 42, 78] line [40, 50, 60, 80]

这个用法是我觉得XYChart最实用的地方：柱子展示实际值，折线展示目标值或参考值，对比效果一目了然。

4.3 柱状图的参数与避坑

柱状图看起来简单，写多了还是有几个容易翻车的点。第一个坑是y轴范围。很多人图方便写0 --> max，如果数据最大值是78，那么y轴到78时柱子会顶到最上方，视觉上很满，反而不利于观察。我习惯把上限设置成最大值的1.2倍，比如最大值78，就写0 --> 100，这样柱子大约占画布高度的四分之三，读图感受最好。如果数据本身没有负数，下限一定写0，不要为了图形好看直接设置成非0的起点，否则会误导读者对数值比例的判断。

第二个坑是类目值里的特殊字符。XYChart的x轴数组用的是JSON风格数组，如果类目里包含逗号、引号或冒号，容易出现解析异常。解决办法是尽量用短标签，比如把“华东区Q1销售额”简写成“华东Q1”，图里更简洁，也减少出错概率。第三个坑常见于老版本项目：代码写好了，其他图都能出来，唯独柱状图是空白。这时先检查Mermaid版本，别急着怀疑代码，很多所谓“bug”都是版本不支持造成的。

最后提醒一句中文显示。Mermaid在浏览器里渲染中文一般没问题，但如果用mermaid-cli导出PDF或图片时出现乱码，通常和运行环境的字体缺失有关。容器或服务器里需要安装包含中文字符集的字体，否则导出图的中文全变成方框。这个坑我帮别人排查过好几次，每次都能省下一大段排查时间。

5. 我这一路踩过的坑：Mermaid代码实战排查清单

5.1 高频报错与解决速查表

在实际项目里用Mermaid，报错信息并不总是指向真正的原因。我自己把遇到过的典型问题整理成了一个速查表，碰到类似情况时可以照着排查：

表格里的每一个问题，我都能对应到一次真实翻车现场。比如节点ID带空格，最开始我写A[登录后跳转]没问题，但写成A[登录后跳转] --> B[回到上一页]也没问题，真正的问题是想到一条从“B页面”到“C页面”的连线，却写了B 页面--> C页面，空格让解析器直接把整行当成非法语法。后来我的规则很简单：所有ID一律用纯英文驼峰命名，所有展示文字如果包含空格或特殊字符，一律加双引号。这个习惯一旦养成，语法错误少一大半。

另一个容易被忽略的问题是Markdown平台对Mermaid代码块的处理。在GitHub上写.md文件时，通常三反引号加mermaid就能渲染，但有些内部Wiki平台默认不做渲染。遇到这种情况不要怀疑语法，先确认平台能力。我在公司里就用过一款只支持部分图类型的工具，流程图正常但时序图不显示，最后发现是平台版本太旧，而不是代码问题。所以遇到不渲染，第一件事是换一个已知支持完整语法的渲染环境做隔离验证。

5.2 团队协作与文档嵌入经验

团队协作里用Mermaid，最划算的一点是图和文字一起进版本库。需求变更时，相关人员提交的不仅仅是一段文字说明，还有一张改动过的图。代码评审时，大家可以逐行看这张图到底改了什么，这种透明度是截图方案无法想象的。因此我建议团队建立一套约定：流程图统一用graph TD方向，时序图统一从调用方到服务方，节点ID统一业务缩写。约定定型后，每个人的图读起来都像同一个人画的，知识库的观感和可维护性都会好很多。

如果业务上需要把图嵌入到PPT或公众号文章里，可以考虑用mermaid-cli把.mmd文件批量导出成SVG或PNG。命令行示例如下：

npx @mermaid-js/mermaid-cli -i input.mmd -o output.svg

这条命令会调用无头浏览器进行渲染，生成的SVG是矢量图，放到PPT或报告里不会失真。导出PNG时，可以用-o output.png，但要注意像素大小和缩放比例，我一般先导出SVG再转一次PNG，控制效果更稳。用这种方式，连“画图五分钟，导出两小时”的问题都省了，因为整个流程已经自动化。

还有一个小技巧：如果文档要给别人编辑，不要把图代码直接揉在长文档中间，而是在文档里引用一个diagrams/流程图.mmd文件。这样其他同事想修改图时，可以直接打开独立文件，不会因误改文档结构而破坏整篇内容。项目复杂以后，这个习惯能让协作效率大幅提升。

6. 写在最后的简记建议

6.1 建一个自己的速查笔记

看完这么多语法，你不需要一次性记住所有内容。我自己的做法是维护一个本地的Mermaid速查文件，里面分门别类放着流程图、时序图、甘特图、柱状图的最小可运行模板。每次遇到新类型，先在速查文件里新建一小节，把官方示例改改成自己的业务场景，再放进正式文档。这样笔记不是收藏夹，而是一个持续生长的工具箱，慢慢会发现画图越来越不依赖搜索引擎。

如果你愿意更进一步，可以给速查文件添加版本信息。比如在文件头部记下“Mermaid 10.6，xychart-beta语法验证通过”，下次换项目环境时，先看版本再判断语法是否能跑。这个细节看起来微不足道，但能省掉很多“为什么以前能画现在不能画”的排查时间。

6.2 最后分享一个使用习惯

我在实际使用中最受益的一个习惯是：画图先想结构，再写代码，最后调样式。很多人一上来就纠结颜色、间距，结果逻辑没理清，反而反复返工。Mermaid默认样式其实已经很干净，除非有特殊要求，否则不需要额外加CSS。真正值得花的精力是定义清楚节点关系，因为图的核心价值是传达逻辑，而不是炫技。官方文档和各种在线渲染器已经覆盖日常需求的九成，只要不从那些“破解下载站”找工具，Mermaid完全能成为你文档工作流里最顺手的那个环节。