1. 为什么 Markdown 画图首选 Mermaid四条技术路线的对比1.1 嵌入式 DSL 语法Markdown 图表的最佳形态我在项目里维护文档已经好几年了一个非常深的体会是技术文档最耗时间的其实不是文字而是图。过去画流程图用的是 draw.io 或者 ProcessOn画完截图贴进文档图是好看但一旦逻辑改一点就得重新打开工具、重新截图、重新上传Git 里完全看不出图的变化。后来换到 Mermaid 之后这个问题才算真正解决。Mermaid 的核心思路是让你用一种接近自然语言的描述性语法DSL去定义图而不是用手去拖动节点。它跟 Markdown 天然是绝配Markdown 管文字Mermaid 管图两者都保存在同一个文本文件里都能被版本管理系统追踪都能在编辑器中直接预览。你改动一行语法下次重新渲染时图就变了整个过程没有“图片”这个概念。这一点在多人协作时尤其有价值。代码评审时同事可以直接在评论里指出“第 38 行这个箭头方向错了”而不是对着截图说“左上角那个方形后面”。文档里所有图的状态、版本、改动记录都跟着代码走任何一次修改都有迹可循对团队的知识沉淀来说这是截图方案完全给不了的体验。1.2 四条画图路线的实际对比为什么 Mermaid 更适合日常使用先把我这些年用过的几种方式拉出来对比一下方便你判断什么场景该用什么。路线 AMermaid 等嵌入式 DSL 语法。最典型的代表是 Mermaid偶尔也能看到使用 PlantUML 的项目。特点是纯文本描述、自动布局、Git 友好。缺点是复杂图表一旦规模变大语法行数会拉得很长而且自动布局意味着你无法像绘图软件那样精确控制每个节点的坐标位置。路线 BPlantUML。功能上跟 Mermaid 重叠度很高时序图、用例图、类图都能画。它的语法更“工程化”支持的种类也更全但引入成本稍高本地运行需要 Java 环境虽然也可以用远程服务器渲染但个人使用体验不如 Mermaid 轻量。如果你只是要在 Markdown 里画几张常见的图Mermaid 的语法明显更友好。路线 CASCII 字符画。用字符拼出框线和箭头适合在纯文本终端或非常老旧的环境里展示。缺点也很致命结构一调整整张图就得重新手排加一行文字可能要让后面所有字符全部右移日常维护成本远高于收益只适合临时“画个示意”。路线 D外部绘图工具导出图片。Visio、draw.io、ProcessOn、XMind 都算这一类。优点是样式精美、布局自由适合做汇报材料缺点是图片跟文档分离改一次图就要重新导一次而且图片内容无法被检索、无法 diff时间一长文档目录里全是“流程图最终版3.png”这种文件根本分不清哪张对应哪版内容。对比维度MermaidPlantUMLASCII 画外部工具截图语法学习成本低中低无与 Markdown 集成原生配合需插件配合直接嵌入图片嵌入Git 可追踪性好好好差自动布局有有无手动布局复杂图表支持中中高差高适合场景技术文档、笔记、轻量排期大型工程建模终端环境汇报材料、精确设计图从这个表能看出Mermaid 最大的价值是“性价比”绝大多数 Markdown 使用场景都是画流程、画交互时序、画简单排期Mermaid 正好覆盖了这几个高频需求同时帮你省掉了图片管理这一整套麻烦事。它不是万能的但在“写文档”这个上下文里它是权衡之后最顺手的选择。1.3 主流 Markdown 环境的兼容现状选一个语法最怕的是写完了没地方渲染。这里列一下我实测过的主流环境环境支持方式备注GitHub / GitLab原生支持在 Markdown 代码块里标注 mermaid 即可语雀 / 飞书文档原生支持部分高级语法存在版本限制Obsidian自带支持预览模式直接渲染Typora自带支持本地渲染体验不错VS Code插件支持推荐 Markdown Preview Mermaid SupportVitePress / VuePress插件/内置需要确认对应版本如果你的团队主要在 GitHub 仓库里写文档那么几乎零配置就可以直接用 Mermaid 画图。如果你用的是公司内部 Wiki 或在线文档平台先花两分钟在编辑器里试一段最简单的渲染代码确认平台支持的 Mermaid 版本再决定要不要大规模铺开。不然辛辛苦苦写了一大堆图上线一看渲染不出来返工成本非常高。2. 流程图代码实例从方框箭头到复杂分支2.1 最小可用示例方向声明与基础节点流程图是 Mermaid 里最常用的图类型语法结构非常直观。最简单的四要素流程graph LR A[开始] -- B{是否登录?} B --|是| C[进入首页] B --|否| D[跳转登录页] C -- E[结束] D -- E第二行的graph LR表示整张图的方向是 Left to Right也就是从左往右排。常见的还有TB从上到下、BT从下到上、RL从右往左。我个人给技术文档画流程时首选TB或LR因为大部分流程图是“入口到出口”的线性逻辑横着排或竖着排都容易读当分支特别多的时候LR能在宽屏上放下更多节点阅读体验比竖着挤在一起好很多。A[开始]表示创建一个叫“开始”的节点方括号代表矩形。B{是否登录?}用花括号表示判断节点也就是菱形这是流程图中“条件分支”的标准画法。--是实线箭头--|是|表示在箭头上标注文字。这套语法几乎不存在理解门槛代码写得顺不顺只取决于你是否能把业务分支拆清楚。2.2 节点形状速查表不同形状的语义做流程图时经常遇到的问题是“这个环节该用什么形状”网上搜“流程图各种框的含义”会得到很多说明。这里结合 Mermaid 的语法整理一个对应关系形状Mermaid 语法语义矩形A[文本]处理步骤、操作圆角矩形A(文本)起止节点常用于“开始/结束”菱形A{文本}判断、条件分支圆形A((文本))连接点、入口出口标识平行四边形A[/文本/]输入输出六边形A{{文本}}准备步骤、异常处理这套形状语义跟通用流程图的画法基本一致。实际使用中不用太纠结某个形状是否“绝对标准”Mermaid 里影响可读性的关键其实是连线的方向是否统一、分支是否清晰而不是节点形状的细微差异。只需要记住几个高频形状矩形代表操作、菱形代表判断、圆角矩形代表起止就足够覆盖大部分场景。2.3 连线类型实线、虚线、粗线、带标签线连线是流程图里表达逻辑关系的关键。Mermaid 提供了几种常用连线形式效果语法实线箭头A -- B实线无箭头A --- B虚线箭头A -.- B粗实线箭头A B带文字箭头A -- 请求 -- B或 A --带文字虚线A -. 回调 .- B举一个实际注册模块的例子把几种连线混用起来graph TB U[用户提交注册表单] --|POST /register| S[服务端校验] S --|参数不合法| F[返回 400] S --|校验通过| D[(写入用户表)] D -.-|触发异步事件| Q[发送欢迎邮件] D -- R[返回 201] F -- R Q -.- R在这个例子里[(用户表)]用了数据库节点的形状-.-表示异步触发的动作。这种“主流程实线、旁路虚线”的习惯能帮读者立刻分清核心链路和辅助链路算是我在实际项目中用过多次的小技巧。推荐每个项目里约定好同步主流程统一用实线异步、通知、回调这类旁路统一用虚线整篇文档读起来会有很强的一致性。2.4 子图分组把复杂的业务模块拆开当流程涉及多个子系统或模块时建议用subgraph做分组。下面是一个用户管理模块的示例逻辑不复杂但分组后结构一目了然graph TB subgraph 前端 A[用户列表页] B[新增用户弹窗] end subgraph 后端 C[用户管理接口] D[权限校验服务] end subgraph 数据库 E[(用户表)] F[(角色表)] end A -- B B --|提交| C C -- D D --|通过| E D --|通过| F C --|写入成功| A使用 subgraph 时有三个容易踩的坑。第一子图里的节点 id 必须全局唯一哪怕两个子图之间毫无关系也不能共用同一个 id否则渲染会错乱。第二子图的end必须与subgraph成对出现少写一个直接渲染失败。第三不要指望通过调整代码内的前后顺序来控制子图在画布上的具体位置Mermaid 的自动布局引擎会根据连线关系重新排布刻意“摆位置”是没用的。顺带说一个容易混淆的概念BPMN 里的网关Gateway是一种可执行的流程建模标准它有自己的一套菱形、叉号符号用于 Flowable、Camunda 这类工作流引擎驱动实际流程实例。Mermaid 画的流程图更像是“给人看的逻辑图”不是可以直接跑起来的流程模型。如果你的目标是让流程引擎自动执行应该用专门的 BPMN 建模工具导出 bpmn 文件而不是在 Mermaid 里画一个“看起来差不多”的图。3. 时序图代码实例把一次 API 调用的完整过程画清楚3.1 参与者、消息与激活框时序图适合表达“多个角色之间按时间顺序发生的交互”在接口设计、排查线上问题时特别好用。我画接口调用链时最常用的模板是sequenceDiagram participant User as 用户 participant Client as 客户端 participant Server as 服务端 User-Client: 打开应用 Client-Server: POST /api/login activate Server Server--Client: 返回 token deactivate Server Client--User: 展示登录成功participant User as 用户在这里给参与者起了中文别名。渲染时图上只显示“用户”代码里用User来引用。这个特性在参与者英文名很长或来自不同系统时非常好用代码还是保持英文标识符展示出来却是中文团队成员不用费力去对应“TS-API-Gateway-01”到底是谁。-是实线箭头表示同步请求--是虚线箭头表示返回结果。这种一实一虚的搭配能清楚刻画“请求-响应”模型。activate Server和deactivate Server会为服务端画一个竖向的激活框生命线表示它在处理请求期间一直处于活动状态。排查超时和慢接口问题时激活框能直观显示哪个服务长时间占用可读性提升很多。简单图没有太多交互角色时可以不加但角色一多建议每个处理节点都标上否则很难看清谁在什么时间段内处理请求。3.2 分支、循环与并行表达真实交互逻辑真实系统的时序往往不是一根直线而是包含成功失败分支、重试、并发调用等结构。Mermaid 的时序图支持alt、loop、par、opt、critical这些逻辑块语法跟伪代码很接近sequenceDiagram participant App participant Gateway participant Auth participant Redis participant DB App-Gateway: 请求业务接口 Gateway-Auth: 校验 token alt token 有效 Auth--Gateway: 用户信息 Gateway-Redis: 查询缓存 alt 命中缓存 Redis--Gateway: 缓存数据 else 未命中缓存 Gateway-DB: 查询数据库 DB--Gateway: 数据 end else token 无效 Auth--Gateway: 401 Gateway--App: 拒绝访问 end Gateway--App: 业务响应这是一段典型的 Spring Boot 后端处理请求时会遇到的路径网关校验 token查缓存命中则直接返回未命中则查数据库。把这段画出来比在文档里用大段文字描述分支路径清楚太多。alt/else/end就是“如果-否则”的分支loop是循环par是并行opt是可选项。嵌套时强烈建议用缩进对齐我见过很多语法错误最后排查下来都是缩进乱了、end配对找不到导致的。3.3 硬件信号时序图为什么我不推荐用 Mermaid搜索“i2c时序图”“spi正常通信时序图”“smbus通讯协议各种时序图”这类内容的人需要先明确一点Mermaid 的时序图本质是“消息序列图”表达的是对象之间的调用顺序而 I2C/SPI/SMBus 这类硬件时序图需要画的是各信号线在时间轴上的高低电平变化时钟周期、建立时间、保持时间都是精确的指标。用 Mermaid 去画这些内容会非常别扭渲染出来也很难看。硬件时序图我一般用 Wavedrom它也是纯文本描述方案通过一段 JSON 渲染成标准的数字波形图支持时钟、注释、总线信号。一个最小示例{ signal: [ { name: clk, wave: p.....|... }, { name: sda, wave: x.3..x|..., data: [A0,A1] }, { name: scl, wave: 0.1.0.1.|... } ]}输出就是带刻度的数字波形图适合放在硬件设计文档里。结论其实很简单软件交互时序用 Mermaid硬件信号波形用 Wavedrom各司其职不要因为 Mermaid 方便就强行用来画所有类型的图。选工具之前先想清楚图表的本质用途能省掉后面一大半返工时间。4. 甘特图代码实例把项目排期写进 Markdown4.1 基础结构section、任务状态与里程碑甘特图是项目管理中很常见的视图Mermaid 对它的支持能把排期直接放进 Markdown跟代码、文档一起维护。一个基础示例gantt title 网站改版项目计划 dateFormat YYYY-MM-DD section 需求阶段 用户调研 :done, t1, 2025-03-01, 7d 原型设计 :done, t2, after t1, 5d section 开发阶段 前端页面 :active, t3, after t2, 10d 后端接口 : t4, after t2, 8d 联调测试 : t5, after t3, 5d section 上线阶段 预发验证 :t6, after t5, 3d 正式发布 :milestone, m1, after t6, 0ddateFormat YYYY-MM-DD指定日期格式section用来分泳道任务行里冒号后面依次是状态done、active和任务 id以及时间定义。after t1表示该任务从t1任务结束后开始这是表达依赖关系最方便的方式。里程碑用milestone标识时长写0d即可渲染出来是一个独立的菱形标记。4.2 关键路径、时间格式与依赖规则甘特图里有个容易被忽略但很有用的标记crit表示关键路径。关键路径上的任务一旦延期整个项目会跟着延期。用法是在任务行里加上critgantt title 迭代排期 dateFormat YYYY-MM-DD section 开发 设计评审 :crit, d1, 2025-04-01, 2d 编码实现 :crit, d2, after d1, 6d 单元测试 :d3, after d2, 3d 集成测试 :crit, d4, after d3, 2d渲染出来后关键路径上的任务条会以红色显示一眼就能看出哪些环节不能拖。日期既可以用YYYY-MM-DD格式写绝对时间也可以像上面这样全部用after id的相对写法。如果团队习惯按迭代排期我推荐尽量用相对写法改动时只需要动第一个任务的日期后面的自动顺延比手动改每一个绝对日期省事得多也不容易改漏。4.3 和 Excel 甘特图相比它的优势到底在哪里搜“甘特图excel制作教程”的人通常是要画一个可以用来做汇报的漂亮图表。Excel 甘特图本质上是用单元格颜色填充出的条形图做出来确实美观手动调整也方便适合一次性汇报场合。但它的维护成本很现实单元格要一格一格涂色日期列要手动对齐更新排期后图形和数据容易错位一旦项目条目多起来整个表格操作起来非常痛苦。Mermaid 甘特图则适合在代码仓库里维护它跟着代码评审走同一套流程。排期发生变化Git 的 diff 能精确显示是哪一行改了排期版本可以在历史记录里随时找回。它不适合做像素级漂亮的对外宣传图但作为团队内部执行的排期表效率和清晰度都足够。我自己通常的做法是内部排期用 Mermaid 放在仓库里维护对外汇报时把导出的图贴进 PPT两头都不耽误。5. 实操环节编辑器配置与图表渲染不出来的排查思路5.1 VS Code 预览 Mermaid 的方案VS Code 是很多写 Markdown 的人的主力编辑器。默认情况下VS Code 的 Markdown 预览并不渲染 Mermaid 图表需要装插件。我常用的组合是安装Markdown Preview Mermaid Support插件装完后按CtrlShiftVMac 上CmdShiftV打开预览代码块里的 Mermaid 语法就会变成图。这是目前我最推荐的本地编辑体验一边写文档一边预览图调样式不用来回切换浏览器。这里有一个非常容易踩的点代码块的语言标注必须写成mermaid也就是代码块围栏写成mermaid。很多人把 Mermaid 代码写在text或者普通代码块里编辑器自然不会去解析它。说明一下本文中为了排版方便统一用markdown展示代码你实际写进 Markdown 文档时围栏语言一定要换成mermaid否则在 GitHub 和 VS Code 里都渲染不出来。5.2 渲染失败时的系统排查链路图表渲染不出来的时候我的排查顺序基本是固定的按这个顺序走能省很多时间打开 mermaid.live把代码原样粘贴进去。如果在线预览也报错就是语法本身的问题直接看错误提示修。如果在线环境正常回到编辑器里检查代码块语言标注是不是mermaid语言写错是最常见的低级原因。确认编辑器插件或平台使用的 Mermaid 版本。quadrantChart、block这类比较新的图类型在旧版本里不支持。逐行精简代码用“删一半看能否渲染”的二分法定位出错的那一行。高发点包括中文括号混用、节点 id 包含空格、文本里出现未转义的{}等特殊字符。如果节点文本里确实需要包含花括号、管道符这类特殊字符用引号包起来比如A[请求 {user} 数据]。这条链路里最关键的是第 1 步。mermaid.live 是官方在线编辑器它给的错误提示通常很明确把报错信息翻译成人话后绝大多数语法问题都能在几分钟内解决。不要在不知道是不是语法错误的情况下盲目改代码先定位再动手。5.3 为什么 mermaid.live 手动编辑后流程图样式会大变这是一个被搜索了很多次的问题。很多人用 mermaid.live 画好一张图手动拖动节点摆好了位置然后发现只要加一个节点或者改一条连线整张图的布局就完全乱掉之前调整的位置全部失效。这不是操作失误而是 Mermaid 的设计如此。Mermaid 的渲染默认走 dagre 自动布局引擎部分场景可切换 elk它的工作方式是根据图的拓扑结构重新计算所有节点坐标。你手动调整的位置只停留在那一次渲染的结果里下次结构一变引擎会基于新结构重新计算一遍坐标之前的手动微调自然就丢失了。所以正确的使用心态是Mermaid 是用来快速生成“可读性尚可”的图的不是用来做像素级精确设计的工具。想让布局更可控能做的有几件事调整节点的定义顺序让分支按阅读方向排列用subgraph把关联节点分组减少跨组连线控制连线的方向和稠密度。如果确实需要精确摆布节点位置、调整每一根线的布局建议导出到 draw.io 或 Figma 这类手动绘图工具里继续编辑而不是在 mermaid.live 里死磕自动布局。6. 进阶玩法主题配置、AI 辅助生成与文档工作流整合6.1 用主题配置统一团队图表风格团队文档如果每人用不同配色整体观感会很乱。Mermaid 支持在图表顶部声明初始化配置%%{init: {theme: forest}}%% graph LR A[需求] -- B[开发] B -- C[测试] C -- D[发布]内置主题包括default、neutral、dark、forest、base。深色模式文档可以用dark大多数团队文档用forest或neutral比较耐看。也可以在配置里覆盖具体主题变量比如调整主题色、字体大小、背景色不过这部分通常只在给客户出文档时需要用到日常使用用内置主题就够。建议在团队文档模板头部统一放一段 init 配置至少能保证所有图风格一致。6.2 用 AI 生成 Mermaid 草稿再人工校正现在很多 AI 编程工具已经内置了生成 Mermaid 图表的能力比如你可能会搜到“claude code 生成时序图的 skill”这类场景就是让 AI 根据代码或描述直接产出时序图。我实际用下来的感受是AI 生成 Mermaid 是个很好的起点比自己面对空白文档敲语法快得多尤其是那些“我脑子里有逻辑但不知道 Mermaid 措辞怎么写”的情况。但 AI 生成的代码不能直接无脑用常见的坑有三个一是节点 id 重复尤其是从多段文本里拼接逻辑时二是loop、alt、par的嵌套层级和end数量对不上渲染时直接报错三是参与者别名定义和后续引用不一致。我的做法是让 AI 生成后再丢进 mermaid.live 过一遍有报错就把报错信息原样贴回去让 AI 修一般一两轮就能稳定。提示词里记得带上“使用 Mermaid 语法”“参与者使用中文别名”“节点 id 保持唯一”这些具体要求生成的图会更贴近你的需求。6.3 导出与集成从文档到发布会话Mermaid 图表毕竟是在浏览器和编辑器里渲染的如果哪一天需要把它放进 PPT 或者对外文档可以用官方命令行工具导出图片。执行npx -p mermaid-js/mermaid-cli mmdc -i input.mmd -o output.svg这条命令会读取一个.mmd文件导出对应的 SVG 或 PNG。配合 CI 流程还能在每次文档改动时自动重新导出图表确保对外发布的图片和仓库里的代码同步不会出现“文档改了图没改”的老问题。如果你用的是 VitePress、VuePress 这类静态站点工具它们基本都支持 Mermaid 集成或官方插件可以把文章里的图表直接渲染到站点上跟文档整体风格保持一致。我在实际项目中的体会是把图变成文本的收益是长久的。用 Mermaid 之后最明显的变化是评审会上讨论到某个分支逻辑时我可以直接当场改文档里的那段 Mermaid 代码刷新预览后大家接着讨论整个过程像改代码一样自然。如果你刚开始接触 Mermaid建议先只掌握流程图和时序图这两种把语法基础打牢后再碰甘特图另外一个小建议是一个图一个代码块别把整篇文档里所有图塞进同一个 Mermaid 块里出问题时定位快很多维护起来也清爽。从第一张流程图开始你很快会发现Markdown 里画图这件事其实可以像写字一样自由。