写技术文档时，用 Mermaid 比手画拖框线快十倍——一段代码生成流程图、时序图、ER 图，改一行图就重渲染。但新手十次有九次卡在右下角的”渲染失败”红字上。
这篇按”14 种图表怎么选 → 90% 报错的真实原因 → 一份排查清单”三段讲清楚，看完就能从”复制示例改两笔出图”升级到”按需求自己写出能渲染的代码”。
14 种图表怎么选
本工具支持 Mermaid v11 全部 14 种主流图表，按使用场景分成 5 组：
| 图表类型 | 用来画 | 触发关键词 |
|---|---|---|
flowchart | 流程、决策、分支 | ”如果…就…”, “失败回到…”, “流程图” |
sequenceDiagram | 时间顺序的对话、调用 | ”调用”, “握手”, “用户操作”, “API 流程” |
classDiagram | 面向对象 / 模块结构 | ”继承”, “实现”, “依赖”, “组合” |
erDiagram | 数据库表关系 | ”1:N”, “外键”, “关联表” |
stateDiagram-v2 | 状态流转 | ”订单状态”, “工单流转”, “协议状态” |
mindmap | 发散思考 | ”脑图”, “知识结构” |
gantt | 排期 | ”项目计划”, “里程碑”, “甘特图” |
pie | 占比 | ”百分比”, “比例饼图” |
xychart-beta | 柱图 / 折线 | ”月度销售”, “趋势图” |
sankey-beta | 流向 | ”用户漏斗”, “能量流” |
quadrantChart | 四象限优先级 | ”紧急重要”, “BCG 矩阵” |
journey | 用户旅程 | ”用户体验”, “情感曲线” |
timeline | 编年史 | ”历史里程碑”, “版本演进” |
gitGraph | git 分支 | ”分支策略”, “合并历史” |
90% 的需求落在前 5 个。不确定时按”这个图想表达什么”问自己：
- “做完 A 才能做 B”——用 flowchart
- “A 喊 B、B 回 A”——用 sequenceDiagram
- “A 有 N 个 B”——用 erDiagram
- “A 状态变成 B”——用 stateDiagram-v2
- “几个点的层级关系”——用 mindmap 或 classDiagram
90% 渲染报错的真实原因
按出现频率排，6 类问题占了几乎全部报错：
1. 首行类型声明拼错或大小写错
sequencediagram ❌ 必须 sequenceDiagram
sequence ❌ 必须 sequenceDiagram
classdiagram ❌ 必须 classDiagram
stateDiagram ❌ 必须 stateDiagram-v2
graph TD ⚠️ 仍能用但已废弃，新写法 flowchart TDMermaid 用首行决定走哪个 parser，拼错直接整图不出。复制模板时连首行一起带——别只 copy 中间部分。
2. 中文标点混入
最隐蔽的坑——肉眼几乎分不清：
A["登录"]：点击 ❌ 中文冒号 ：
A --> B：登录 ❌
participant U as 用户，浏览器 ❌ 中文逗号 ，
正确写法：
A["登录"]: 点击 ✓
A --> B: 登录 ✓
participant U as 用户, 浏览器 ✓来源几乎都是从微信、钉钉、飞书文档复制黏贴。养成习惯：粘贴后全文搜 ： ， 。 （ 一遍。
3. 箭头语法 / 图表类型不匹配
flowchart 用 -->（两减号一尖括号），sequenceDiagram 用 ->> / -->>：
flowchart：
A --> B 实线箭头（也可加文字 A -->|登录成功| B）
A -.-> B 虚线箭头
A ==> B 粗箭头
A --- B 无箭头连线
sequenceDiagram：
A->>B: 同步调用 实线 + 实心箭头
B-->>A: 返回响应 虚线 + 实心箭头
A-)B: 异步消息 不等返回
A-xB: 连接断开 异常 / 拒绝混用规则会渲染失败或样式诡异。记忆口诀：流程图用 -->，时序图用 ->>。
4. 标签里的特殊字符未转义
节点标签里有 () [] {} | " # 时，必须用双引号包：
A[函数 foo(x)] ❌ 括号会被当成圆角节点
A["函数 foo(x)"] ✓
B[第 1 步 [废弃]] ❌ 方括号嵌套
B["第 1 步 [废弃]"] ✓
C{是否登录?} ✓ 英文问号 OK
C{是否登录？} ❌ 中文问号时序图的注释 Note right of 也常踩这个坑——文字含中文标点时报错，加引号无效，只能改文案：
Note right of A: 校验，超时
❌ 中文逗号
Note right of A: 校验, 超时
✓5. 版本语法差异
Mermaid 多个版本语法有微调，老教程的写法在新版本可能失效：
| 旧写法 | 新写法 |
|---|---|
graph TD | flowchart TD（仍兼容但推荐用新名） |
stateDiagram | stateDiagram-v2（强烈推荐 v2，渲染更准） |
sequenceDiagram\n A->B: x（单尖箭头） | A->>B: x（双尖更稳） |
pie showData | pie title 标题（v10+ showData 单独配置） |
本工具用的是 v11，默认按新语法走。
6. 保留字冲突 / 节点 ID 含连字符
flowchart TD
end --> next ❌ end 是保留字
task-1 --> task-2 ❌ 连字符在 ID 里被解析为减号
正确：
Stop --> Next ✓ 改名
task1 --> task2 ✓ 用下划线或小驼峰
"task-1" --> "task-2" ✓ 或者加引号flowchart 的保留字：end、subgraph、direction、click。
flowchart 节点形状速查
最常用的图表，节点形状全靠括号选：
| 写法 | 形状 | 用途 |
|---|---|---|
A[文字] | 矩形 | 默认，普通步骤 |
A(文字) | 圆角矩形 | 起点 / 终点 |
A((文字)) | 圆形 | 状态 / 节点标识 |
A{文字} | 菱形 | 判断 / 决策 |
A>文字] | 旗帜 | 标记 / 标签 |
A[/文字/] | 平行四边形 | 输入 / 输出 |
A[\文字\] | 反向平行四边形 | 输入 / 输出 |
A[(文字)] | 圆柱 | 数据库 |
A[[文字]] | 子程序 | 嵌套调用 |
实战建议：一张图里 ≤ 3 种形状——形状用多了反而看不清重点。判断用菱形 + 步骤用矩形 + 数据库用圆柱基本够用。
时序图的 4 种箭头
A->>B: 同步请求 实线 + 实心箭头
B-->>A: 同步返回 虚线 + 实心箭头（视觉惯例：去同步、回虚线）
A-)B: 异步消息 不等返回，发完就走（如 MQ）
A-xB: 连接断开 异常 / 拒绝 / 超时视觉惯例：实线表示”主动调用”，虚线表示”被动响应”。所以 A->>B 后面通常跟 B-->>A——别都写实线，看图人会一头雾水。
ER 图的基数符号
USER ||--o{ ORDER : places
↑↑ ↑↑
左 右左到中、右到中两端独立读：
| 符号 | 最少 | 最多 |
|---|---|---|
|| | 1 | 1 |
|o | 0 | 1 |
}o | 0 | 多 |
}| | 1 | 多 |
实战常用 3 组：
||--o{：1 对 0..N（USER 可有 0 或多个 ORDER）||--|{：1 对 1..N（ORDER 至少有 1 个 ORDER_ITEM）}o--o{：多对多可选（USER 与 ROLE 通过中间表）
画错的代价：DBA 一眼看出业务逻辑漏洞——空订单是否合理？空购物车能否结账？基数图先回答业务问题，再回答数据库问题。
中文标点的彻底解决
全文搜替换比逐行修方便。Mermaid 不认的中文字符全列出：
| 中文 | 替换为 |
|---|---|
： | : |
， | , |
（ ） | ( ) |
； | ; |
"" '' | " '（更建议都用半角双引号） |
？ | ?（用在 flowchart 判断节点 {是否成功?}） |
！ | ! |
。 | 通常出现在标签文末，直接删除或换 . |
例外：标签 / 注释内容里的中文标点视觉上是允许出现的，但容易引发后续 parser 误判——全部换半角最稳。
导出与分享
右上角三个导出按钮：
| 按钮 | 输出 | 适合 |
|---|---|---|
| 复制 SVG | SVG 源码到剪贴板 | 贴到 README、Notion 富文本（直接渲染） |
| 导出 SVG | 下载 .svg 文件 | 矢量印刷、再编辑（Illustrator 可改） |
| 导出 PNG | 下载 .png 文件（2x 高清） | 贴 PPT、微信、公众号（兼容性最广） |
分享链接：点”分享”按钮，代码 base64 编码后塞进 URL hash（/tools/mermaid/#code=xxxxx）。
- 全部在 hash 里，不发到服务器——本工具完全离线渲染
- 别人打开链接会自动加载你的代码并渲染
- 代码越长链接越长——超长代码（如 200 行甘特图）链接可能超过 2000 字符，少数浏览器会截断
需要长期保存的图——先复制代码到笔记里，链接当临时分享用。
渲染失败时的 5 分钟排查路径
| 步骤 | 操作 | 解决率 |
|---|---|---|
| 1 | 检查首行类型声明拼写大小写 | 30% |
| 2 | 全文搜中文标点 ：，（）"" 替换为半角 | 40% |
| 3 | 检查箭头与图表类型匹配（--> vs ->>） | 15% |
| 4 | 给含特殊字符的节点标签加双引号 | 10% |
| 5 | 看右下角错误信息前 50 个字到 mermaid.js.org 搜 | 5% |
90% 的报错在前两步就能定位。养成”粘贴代码后先搜一遍中文标点”的习惯，比一行行肉眼对照快得多。
写文档时的最佳实践
- 小图优先：一张图 ≤ 15 个节点。超过的拆成两张或换 [[mermaid]] 子图（subgraph）
- 代码与图同源：把 Mermaid 代码直接贴到 Markdown 里，GitHub / Notion / 飞书都支持原生渲染，别把图导成 PNG 再贴——图改一次要重传一次
- 正式排版时：复杂图（多分支决策、跨系统时序）转 SVG 印刷 / 导出；草图阶段用 [[whiteboard]] 自由发散
- 数据可视化：饼图 / 柱图 / 折线如果数据多 (>10 项) 用 [[chart-maker]] 更顺手，Mermaid 的
pie/xychart更适合 3-8 项的快速示意
写技术文档把 Mermaid 用顺手了，README、设计文档、接口说明的视觉传达密度会大幅提升——代码即图，diff 友好，版本可控，比来回拖 draw.io 拷图爽得多。