Mermaid 详解：用文本画图的 JavaScript 图表库
画一张流程图，传统方式是拖拽 Visio 或 draw.io 的方框与连线，改一次布局重来一次。而 mermaid-js/mermaid（Mermaid）把画图变成了写代码：用几行类 Markdown 的文本描述节点与关系，渲染引擎自动生成流程图、时序图、甘特图等十几种图形。约 75k Star，是 GitHub 上最流行的图表库，且原生集成进 GitHub / GitLab 的 Markdown 渲染。本文从核心语法、图表类型、嵌入方式到实践技巧，完整拆解。
1、项目概述
Mermaid 定位为"基于 JavaScript 的图表生成与图表绘制工具"，口号是 Generation of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown。由 Knut Sveidqvist 于 2014 年发起，如今已是 CNCF 毕业项目 C4 模型文档化的常用工具之一，GitHub / GitLab / Notion / Obsidian 均原生支持。
基本形态与生态：
- 形态：浏览器端 JS 库（npm 包）+ 在线编辑器 mermaid.live + CLI 渲染工具
- 协议为 MIT，商用与嵌入无约束
- GitHub 仓库 markdown 代码块标记 mermaid 即自动渲染，零配置
- 兄弟项目：PlantUML 同为文本绘图，但依赖 Java 与本地服务
2、四大核心能力
Mermaid 的能力可以归成四根支柱，覆盖"文本到图"的完整链路。
四根支柱：
- 图表类型：流程图、时序图、类图、状态图、ER 图、甘特图、饼图、思维导图等十几种
- 文本语法：类 Markdown 声明式描述，节点/连线/样式一句话搞定
- 渲染集成：浏览器直接渲染、静态导出 SVG/PNG、VitePress/Docusaurus 插件化
- 可交互扩展：点击事件、Tooltip、动画，图不只是静态图
能力要点：
1. 文本即版本：图进 Git，diff 可审、merge 可合，彻底告别"图与代码两张皮"
2. 自动布局：无需手动对齐，节点增删后引擎重排
3. 十余种图共用一套集成方式，学习成本集中一次
3、基础语法：流程图与节点连线
最常用的是流程图（flowchart），声明方向、节点形状与连线类型即可成图。
flowchart TD
A[用户请求] --> B{网关鉴权}
B -->|通过| C[业务服务]
B -->|拒绝| D[401 返回]
C --> E[(数据库)]
C --> F([缓存])语法要点：
1. TD/LR 声明布局方向（自上而下 / 从左到右）
2. 节点形状：[] 矩形、{} 菱形（判断）、() 圆角、(()) 圆形、[()] 数据库、 [[]] 子例程
3. 连线类型：--> 实线箭头、--- 无箭头、-.-> 虚线、==> 粗线，线上文字用 |文字| 包裹
4. style 指令可单独给节点上色：style A fill:#f96,stroke:#333
4、时序图：接口的标准画法
时序图（sequenceDiagram）描述多角色之间的消息往来，是接口文档与设计评审的高频图。
sequenceDiagram
participant C as 客户端
participant S as 服务端
participant D as 数据库
C->>S: POST /login
S->>D: 查询用户
D-->>S: 用户记录
alt 密码正确
S-->>C: 200 + Token
else 密码错误
S-->>C: 401
end时序要点：
1. ->> 实线箭头、-->> 虚线箭头（常用于返回值）
2. alt/else、loop、opt、par 表达分支、循环、可选与并发块
3. participant 别名让长名字图仍紧凑；activate/deactivate 画生命线激活
4. Note over A,B: 备注可横跨多个角色
5、其他高频图：类图、甘特图与饼图
除流程图与时序图外，还有三类图在日常文档中出现率最高。
高频图型：
- 类图：类名/属性/方法与继承组合关系，技术设计文档常用
- 甘特图：任务时间线，按日期排列里程碑与依赖
- 饼图：占比展示，三行语法即出图
pie title 缓存命中率分布
"命中" : 82
"未命中" : 13
"穿透" : 5
gantt
title 迭代排期
dateFormat YYYY-MM-DD
section 开发
接口开发 :a1, 2025-09-01, 5d
联调 :after a1, 3d使用要点：
1. 类图支持泛化 --|>、组合 *-- 、聚合 o-- 等 UML 标准关系
2. 甘特图 dateFormat 决定日期解析格式，任务可用 after 串联依赖
3. 饼图、mindmap、timeline 等图语法极简，适合快速插入文档
6、集成与导出
Mermaid 的落地路径主要有三条：Markdown 内嵌、网页集成、命令行导出。
# 方式一：Markdown 代码块（GitHub/GitLab/多数文档站原生渲染）
```mermaid
flowchart LR
A --> B
```
# 方式二：CLI 导出 SVG / PNG
npm install -g @mermaid-js/mermaid-cli
mmdc -i input.mmd -o output.svg
# 方式三：网页中渲染
import mermaid from 'mermaid';
mermaid.initialize({ startOnLoad: true });集成要点：
1. README、Issue、PR 描述里直接写 mermaid 代码块，GitHub 自动出图
2. mmdc 基于 Puppeteer 截图，CI 中可批量把 .mmd 转成图片产物
3. mermaid.live 在线编辑器支持实时预览与分享链接，适合临时讨论
4. VitePress、Docusaurus、 MkDocs 均有官方或社区插件
7、定位对比：绘图工具三选一
把 Mermaid 与 PlantUML、draw.io 放在一张桌上，各自的位置清晰起来。
三者对比：
- Mermaid：JS 纯前端渲染，GitHub 原生支持，上手最快，图型覆盖主流场景
- PlantUML：UML 表达力更深，但依赖 Java 环境，渲染需本地服务或服务端
- draw.io：拖拽式自由布局，精细排版最强，但无法 diff、难版本化
选型建议：
1. 图要进仓库随文档演进 → Mermaid
2. 重度 UML 建模、需要 C4 等扩展 → PlantUML
3. 架构大图、海报级精细排版 → draw.io
4. 组合玩法：日常设计用 Mermaid 进 Git，对外汇报图导出 SVG 后用 draw.io 精修
8、总结
Mermaid 是最流行的文本绘图库（约 75k Star、MIT 协议）：以类 Markdown 声明式语法覆盖流程图、时序图、类图、甘特图等十几种图型，自动布局免对齐，图与文档同源进 Git；渲染链路覆盖 GitHub 原生 Markdown、浏览器 JS 库与 mmdc 命令行导出，从 README 插图到 CI 批量出图一条龙。
落地建议：先把 flowchart 与 sequenceDiagram 两种语法练熟，覆盖八成文档场景；写设计文档时直接在 Markdown 里画图，评审改动走 PR diff；需要图片产物时用 mmdc 进 CI 自动导出。对于想让图表与代码一起版本化演进的团队，Mermaid 是必要的文档基础设施。
