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代码块写图，按Ctrl+Shift+V预览即可看到渲染结果。这个方式适合日常写文档。
第三种是支持 Mermaid 的平台。GitHub 的 README、Issue、Wiki 都支持 Mermaid 代码块，Obsidian 和 Typora 也是开箱即用。你只要用正确的代码块标记包裹，平台会自动渲染。
2.2 一个必须记住的代码块骨架
不管在哪个平台，Mermaid 的代码块结构都是固定的：
graph TD A[节点文本] --> B[另一个节点]第一行是图表类型关键字，比如graph、sequenceDiagram、classDiagram。后面是具体的节点和连线定义。关键字拼错、方向写错、括号不匹配，都会导致渲染失败。所以我的建议是：先复制一个能跑的最小示例，确认渲染成功，再往上加内容。
如果你在本地用命令行批量导出图片，可以装mermaid-cli：
npm 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、opt：
sequenceDiagram 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 *-- Engine |
o-- | 聚合 | 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包裹代码，按Ctrl+Shift+V打开预览。如果预览里出现图形，说明插件工作正常。如果显示的是原始代码文本，说明插件没装好或者代码块标记写错了。
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写成graphh，sequenceDiagram写成sequenceDiagram（大小写错），stateDiagram-v2写成stateDiagram。Mermaid 的关键字是大小写敏感的，graph和Graph不是一回事。排查方法：对照本文的骨架，逐字检查第一行。
5.2 括号不匹配
流程图的节点形状靠括号区分，A[文本]少一个]，或者B{判断}写成B{判断]，都会导致解析失败。子图的subgraph和end必须成对出现，循环的loop和end也是。排查方法：从内到外数括号，或者把复杂图拆成小块逐个验证。
5.3 特殊字符没转义
节点文本里出现&、<、>、引号时，容易出问题。比如A[他说"你好"]里的引号会干扰解析。解决办法是用双引号包裹整个文本并转义内部引号：A["他说 \"你好\""]。HTML 实体也可以，&表示&。
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展开时序图骨架。这样你不需要每次从零开始记语法，把精力留给真正重要的逻辑表达。绘图是手段，把逻辑讲清楚才是目的。
