最近整理团队知识库我又把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纯文本描述Markdown文档、代码仓库、自动化生成复杂自由布局和精细排版较吃力PlantUML纯文本描述严格的UML图、架构图需要Java运行环境语法更繁琐draw.io / Visio图形拖拽思维导图、网络拓扑、手工排版文件不易做文本diff协同效率偏低从这个表就能看出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 srchttps://cdn.jsdelivr.net/npm/mermaid10/dist/mermaid.min.js/script script mermaid.initialize({ startOnLoad: true }); /script pre classmermaid 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-DDsection表示分组任务名后面的: 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建议安装mermaid10.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声明这是一个XYChartx-axis后面的数组是柱状图的类别标签对应每个柱子下方的中文或英文名称y-axis后面先写坐标轴的单位说明再接0 -- 100表示数值范围从0到100bar后面是柱子值列表与x轴数组按顺序一一对应。这段代码渲染后你会得到一张干净的双轴柱状图不需要额外配置颜色、间距或网格线默认样式已经足够用于日常报告。如果柱子太多或者想调整方向可以加一个horizontal关键字让柱子变成横向条形图xychart-beta horizontal title 编程语言使用人数 x-axis [Python, JavaScript, Go, Rust] y-axis 人数 0 -- 100 bar [80, 70, 45, 20]横向图在类目名较长时更不容易被截断。另外想在同一张图里看趋势线和柱状对比可以在bar后面再加上一行lineMermaid会把柱状图与折线图融合显示。例如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报错信息并不总是指向真正的原因。我自己把遇到过的典型问题整理成了一个速查表碰到类似情况时可以照着排查现象常见原因建议处理图上显示Syntax error弹窗节点ID或文本用了空格、括号等未转义字符给文本加英文双引号节点ID改驼峰命名整块代码不渲染原样显示文档平台不支持Mermaid或起始关键字写错确认graph、sequenceDiagram等拼写无误换支持Mermaid的平台柱状图区域完全空白Mermaid版本低于10.3升级Mermaid或在线编辑器版本时序图消息里的中文或括号显示错乱消息文本包含特殊符号用引号包裹消息内容导出图片时中文变方框渲染环境缺少中文字体安装中文字体或改用带字体的PDF导出方案表格里的每一个问题我都能对应到一次真实翻车现场。比如节点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.6xychart-beta语法验证通过”下次换项目环境时先看版本再判断语法是否能跑。这个细节看起来微不足道但能省掉很多“为什么以前能画现在不能画”的排查时间。6.2 最后分享一个使用习惯我在实际使用中最受益的一个习惯是画图先想结构再写代码最后调样式。很多人一上来就纠结颜色、间距结果逻辑没理清反而反复返工。Mermaid默认样式其实已经很干净除非有特殊要求否则不需要额外加CSS。真正值得花的精力是定义清楚节点关系因为图的核心价值是传达逻辑而不是炫技。官方文档和各种在线渲染器已经覆盖日常需求的九成只要不从那些“破解下载站”找工具Mermaid完全能成为你文档工作流里最顺手的那个环节。