Mermaid 新手完全指南：从语法到技巧，一张图入门文档即代码

1. 为什么我劝你先别急着画图而是先搞懂 Mermaid 的“文档即代码”如果你第一次听到 Mermaid可以把它理解成“用写 Markdown 的方式画图”。你不再需要打开拖拽式画图工具一个个对齐箭头、调整方框大小而是写几行类似下面这样的文本渲染器就会把它变成一张流程图graph TD A[开始] -- B{条件判断} B --|是| C[执行操作] B --|否| D[结束]Mermaid 能做什么它支持流程图、时序图、类图、状态图、甘特图、饼图等十几种图表GitHub、GitLab、Notion、Obsidian、Typora 等平台都原生支持。适合谁适合所有需要在技术文档、项目 README、知识库、博客里嵌入图表的开发者尤其是那些受够了“图片改一个字就要重新导出”的人。“文档即代码”这个词听起来有点大但落到 Mermaid 上非常具体图表源文件是纯文本可以进 Git 版本控制可以 diff可以 review可以随代码一起发布。你改一个节点名字提交记录里清清楚楚而不是丢一张二进制图片进去谁也说不清改了什么。这篇指南面向首次接触 Mermaid 的开发者我会从最小可运行示例开始把配置骨架、渲染验证、常见报错排查一步步走完。你不需要任何绘图基础只要会写 Markdown 就能跟上。2. 前置准备把 Mermaid 跑起来再谈语法在写复杂图表之前先确保你的环境能渲染 Mermaid。这一步很多人跳过结果后面遇到“代码没错但图出不来”就开始怀疑语法其实是渲染环境的问题。2.1 三种最省事的起步方式第一种是在线编辑器。打开 Mermaid Live Editor左边写代码右边实时出图最适合学习和调试语法。你不需要安装任何东西浏览器打开就能用。第二种是 VS Code 插件。在扩展市场搜索 “Markdown Preview Mermaid Support”安装后在.md文件里用mermaid代码块写图按CtrlShiftV预览即可看到渲染结果。这个方式适合日常写文档。第三种是支持 Mermaid 的平台。GitHub 的 README、Issue、Wiki 都支持 Mermaid 代码块Obsidian 和 Typora 也是开箱即用。你只要用正确的代码块标记包裹平台会自动渲染。2.2 一个必须记住的代码块骨架不管在哪个平台Mermaid 的代码块结构都是固定的graph TD A[节点文本] -- B[另一个节点]第一行是图表类型关键字比如graph、sequenceDiagram、classDiagram。后面是具体的节点和连线定义。关键字拼错、方向写错、括号不匹配都会导致渲染失败。所以我的建议是先复制一个能跑的最小示例确认渲染成功再往上加内容。如果你在本地用命令行批量导出图片可以装mermaid-clinpm install -g mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.png这条命令把diagram.mmd文件转成 PNG。-i是输入文件-o是输出文件。实测下来CI 里批量生成文档配图非常方便。3. 可复制配置六种常用图表的语法骨架这一节是全文的核心。我把最常用的六种图表各给一个可直接复制的骨架你改改文字就能用。每种我都会标出关键语法点避免你踩坑。3.1 流程图节点形状与连线类型流程图是使用频率最高的。方向关键字有TD从上到下、BT从下到上、LR从左到右、RL从右到左。graph LR A[矩形节点] -- B(圆角矩形) B -- C{菱形判断} C --|是| D([体育场形]) C --|否| E[(数据库)] D -- F((圆形)) E -- F节点形状由括号决定[]是矩形()是圆角{}是菱形([])是体育场形[()]是数据库圆柱(())是圆形。连线方面--是带箭头实线---是无箭头实线-.-是虚线箭头是粗线箭头。连线上加文字用--|文字|。子图用subgraph和end包裹graph TD subgraph 客户端 A[浏览器] -- B[前端] end subgraph 服务端 C[API] -- D[(数据库)] end B -- C样式控制有两种方式。单节点用style A fill:#f9f,stroke:#333批量用classDef定义样式类再class应用graph TD classDef done fill:#9f9,stroke:#333 classDef doing fill:#ff9,stroke:#333 A[已完成]:::done -- B[进行中]:::doing注意:::是内联应用样式类的写法比单独写一行class更紧凑。3.2 时序图参与者、消息与激活框时序图用来描述对象之间的消息传递顺序比如 API 调用链、登录流程。sequenceDiagram participant U as 用户 participant S as 服务端 U-S: 提交登录请求 activate S S--U: 返回 Token deactivate S Note right of U: 保存 Tokenparticipant定义参与者并起别名-是实线箭头同步消息--是虚线箭头返回消息-)是异步消息。activate和deactivate控制激活框也可以简写成U-S:和S---U:。循环和条件用loop、alt、else、optsequenceDiagram participant C as 客户端 participant S as 服务端 loop 每分钟一次 C-S: 心跳检测 end alt 成功 S--C: 200 OK else 失败 S--C: 500 错误 end3.3 类图关系符号速查类图用来表达面向对象设计。属性方法前的符号公有-私有#保护。classDiagram class Animal { String name int age eat() void } class Dog { bark() void } Animal |-- Dog关系符号是类图最容易记混的地方我整理成表格语法关系示例|--继承Dog |-- Animal*--组合Car *-- Engineo--聚合Department o-- Employee--关联Student -- Course..依赖ClassA .. ClassB|..实现Fly |.. Bird接口用interface注解写在类名后面。3.4 状态图状态流转与复合状态状态图描述系统状态变化比如订单流转。stateDiagram-v2 [*] -- 待支付 待支付 -- 已支付: 付款成功 已支付 -- 已发货: 仓库打包 已发货 -- [*]: 签收 待支付 -- [*]: 取消订单[*]表示起点或终点转换条件写在冒号后面。复合状态用嵌套的state块表达。3.5 甘特图任务排期与里程碑甘特图展示项目时间线。gantt title 项目计划 dateFormat YYYY-MM-DD section 设计阶段 需求分析 :done, a1, 2026-06-01, 3d 原型设计 :active, a2, after a1, 2d section 开发阶段 编码 :crit, a3, after a2, 5d 测试 :a4, after a3, 3d 里程碑 :milestone, m1, after a4, 0ddateFormat定义日期格式section分隔任务组任务语法是任务名 : 状态, 别名, 开始时间, 持续时间。状态有done、active、crit里程碑持续时间设为0d。3.6 饼图占比展示饼图最简单数据用键值对值会自动归一化。pie showData title 技术栈占比 JavaScript : 45 Python : 30 Go : 15 其他 : 10showData可选加上后会在图上显示数值标签。4. 验证请求确认你的图表真的渲染成功了写完代码不等于渲染成功。我见过太多人代码看着没问题但图就是出不来。所以每写完一段都要做一次渲染验证。4.1 在线编辑器的验证动作把代码粘贴到 Mermaid Live Editor 左侧右侧如果出现图形说明语法通过。如果右侧显示红色错误提示它会告诉你第几行、什么类型的错误。这是最快的验证方式。4.2 本地 Markdown 的验证动作在 VS Code 里用mermaid包裹代码按CtrlShiftV打开预览。如果预览里出现图形说明插件工作正常。如果显示的是原始代码文本说明插件没装好或者代码块标记写错了。4.3 命令行导出的验证动作用mmdc导出时如果命令返回 0 且生成了图片文件说明渲染成功mmdc -i diagram.mmd -o diagram.png ls -lh diagram.png如果报错终端会输出具体的解析错误行号。我试过把一段有语法问题的代码丢给mmdc它会明确告诉你Parse error on line 4比在线编辑器还直接。4.4 一个完整的验证示例下面这段代码你可以直接复制到 Live Editor 验证graph TD A[开始] -- B{是否登录} B --|是| C[进入首页] B --|否| D[跳转登录页] D -- E[提交凭证] E -- B渲染成功后你会看到一个从上到下的流程图包含矩形、菱形节点和带标签的连线。如果这个能跑通说明你的环境没问题可以继续加复杂度。5. 本篇常见错排查渲染失败到底卡在哪这一节我按报错频率从高到低排列基本覆盖新手 90% 的坑。5.1 关键字拼写错误最常见的错误。graph写成graphhsequenceDiagram写成sequenceDiagram大小写错stateDiagram-v2写成stateDiagram。Mermaid 的关键字是大小写敏感的graph和Graph不是一回事。排查方法对照本文的骨架逐字检查第一行。5.2 括号不匹配流程图的节点形状靠括号区分A[文本]少一个]或者B{判断}写成B{判断]都会导致解析失败。子图的subgraph和end必须成对出现循环的loop和end也是。排查方法从内到外数括号或者把复杂图拆成小块逐个验证。5.3 特殊字符没转义节点文本里出现、、、引号时容易出问题。比如A[他说你好]里的引号会干扰解析。解决办法是用双引号包裹整个文本并转义内部引号A[他说 \你好\]。HTML 实体也可以amp;表示。5.4 主题配置不兼容%%{init: {theme: forest}}%%这类初始化指令如果写错整个图会渲染失败。排查方法先把%%{init}%%那行删掉看是否能渲染。如果能说明是配置问题再逐项检查配置项拼写。5.5 平台支持差异GitHub 支持大部分图表但极少数新型图表比如mindmap可能滞后。某些平台需要单独插件。遇到不兼容时降级为flowchart通常能解决。排查方法换到 Mermaid Live Editor 验证如果那边能渲染说明是平台问题而不是语法问题。5.6 连线文字里的竖线冲突--|是|这种写法里竖线是分隔符。如果文字本身包含竖线会解析错乱。解决办法是避免在连线标签里用竖线或者改用-- 文字 --的写法。6. 语义一致 CTA把 Mermaid 接进你的文档工作流Mermaid 本身是纯前端渲染不依赖任何后端服务。但如果你想把图表生成、文档构建、CI 流程串起来或者用大模型辅助生成 Mermaid 代码可以借助 API 能力来做自动化。比如你想让模型根据一段需求描述直接输出 Mermaid 代码或者批量把.mmd文件转成图片嵌入文档可以走 API 接入的方式。先到 TaoToken API Keys 创建一个 Key然后参考 接入文档 把模型调用接进你的脚本。如果你只是想先验证模型能不能稳定输出 Mermaid 语法可以直接在 模型对话 里试几轮确认输出格式符合预期再写进自动化流程。对于长期做文档工程或 Agent 开发的场景频繁调用模型生成图表代码会产生持续消耗可以看看 Coding Plan 是否适合你的使用节奏。如果你用 Claude Code 这类工具做开发Anthropic 兼容接入的配置可以参考 ClaudeCodeAnthropic 接入说明把 Mermaid 生成能力嵌进你的编码工作流。最后给你一个我常用的技巧把常用的 Mermaid 骨架存成代码片段VS Code 的 User Snippets写文档时输入mmflow就能展开一个流程图骨架输入mmseq展开时序图骨架。这样你不需要每次从零开始记语法把精力留给真正重要的逻辑表达。绘图是手段把逻辑讲清楚才是目的。