一、Mermaid 是什么？
Mermaid 是一个基于 JavaScript 的图表绘制工具，核心特点是 用文本描述生成图表。对我而言，它的价值在于：
- 纯文本维护：图表和文档写在一起，不用截图、不用拖拽、不用保存额外图片文件。
- 版本控制友好：
.md文件里直接改几行文字，图表就变了，Git diff 清晰可读。 - 嵌入 Markdown：大部分笔记软件和 Git 托管平台（GitHub、GitLab）原生支持。
以前画流程图，我要么在 Draw.io 里拖拽然后截图，要么用 PlantUML。Mermaid 的语法比 PlantUML 更简洁，而且和 Markdown 无缝集成，我现在的技术笔记里所有图表都改用 Mermaid 了。
二、怎么用 Mermaid？
1. 在 Markdown 中使用
用 mermaid 代码块包裹：
```mermaid
graph TD
A[开始] --> B{判断}
B -->|是| C[结束]
B -->|否| A
```渲染效果（在你的网站上会显示为图表）：
graph TD
A[开始] --> B{判断}
B -->|是| C[结束]
B -->|否| A三、常用图表类型及语法
1. 流程图（Flowchart）
最常用的图表类型，用于描述流程、逻辑、架构。
基本语法：
graph TD
Start --> Process[处理步骤]
Process --> Decision{条件判断}
Decision -->|是| End[结束]
Decision -->|否| Process节点形状：
| 形状 | 语法 | 示例 |
|---|---|---|
| 矩形（默认） | 节点ID[文本] | A[开始] |
| 圆角矩形 | 节点ID(文本) | B(处理) |
| 菱形（决策） | 节点ID{文本} | C{判断?} |
| 圆形（起始/结束） | 节点ID((文本)) | D((结束)) |
| 圆柱形（数据库） | 节点ID[(文本)] | DB[(数据库)] |
| 六边形 | 节点ID{{文本}} | E{{准备}} |
连线方向：
graph TD：从上到下（Top-Down）graph LR：从左到右（Left-Right）graph BT：从下到上graph RL：从右到左
带标签的连线：
A -->|标签文字| B子图（分组）：
subgraph 子图标题
A
B
end示例：登录流程：
graph TD
Start((开始)) --> Input[输入用户名密码]
Input --> Validate{验证}
Validate -->|成功| Dashboard[进入仪表盘]
Validate -->|失败| Error[显示错误]
Error --> Input
Dashboard --> End((结束))踩坑记录：节点 ID 不能包含空格。如果需要空格，用中括号包裹文本即可，比如
A[我的节点]。连线时标签用竖线包裹，-->|标签|，注意竖线前后不要加多余空格。
2. 时序图（Sequence Diagram）
用于描述多个参与者之间的交互顺序，特别适合画 API 调用、消息传递流程。
基本语法：
sequenceDiagram
participant 用户
participant 前端
participant 后端
用户->>前端: 点击登录按钮
前端->>后端: POST /api/login
后端-->>前端: 返回 token
前端-->>用户: 跳转首页参与者声明：
participant：标准参与者actor：角色（小人图标，部分渲染器支持）- 可以不声明，直接用，但推荐声明以控制顺序
消息类型：
| 符号 | 含义 |
|---|---|
->> | 实线箭头（同步请求） |
-->> | 虚线箭头（异步响应） |
-> | 实线无箭头 |
-->> | 虚线无箭头 |
-) | 实线末尾带 X（异步） |
--x | 虚线末尾带 X |
激活框（生命线）：
activate 后端
后端-->>前端: 响应
deactivate 后端简写：+ 和 -
用户->>+后端: 请求
后端-->>-用户: 响应标注（Note）：
Note left of 用户: 用户侧备注
Note right of 后端: 服务侧备注
Note over 用户,后端: 跨参与者备注循环/条件/可选：
loop 每秒一次
用户->>后端: 心跳
end
alt 成功
后端-->>用户: 200 OK
else 失败
后端-->>用户: 500 Error
end示例：用户注册时序图：
sequenceDiagram
actor 用户
participant 前端
participant 后端
participant 数据库
用户->>前端: 填写注册信息
前端->>后端: POST /register
后端->>数据库: 查询用户名是否存在
alt 用户名已存在
数据库-->>后端: 返回存在
后端-->>前端: 409 冲突
前端-->>用户: 提示用户名被占用
else 用户名可用
数据库-->>后端: 不存在
后端->>数据库: 插入新用户
数据库-->>后端: 成功
后端-->>前端: 201 注册成功
前端-->>用户: 跳转登录页
end个人经验：时序图最常用于梳理接口调用关系。我一般在设计新功能前，先用时序图画一遍交互流程，能提前发现很多逻辑漏洞。
3. 甘特图（Gantt Chart）
项目管理/学习计划/任务排期，特别适合做个人学习路线图。
基本语法：
gantt
title 学习计划 - 2025年Q2
dateFormat YYYY-MM-DD
section 基础学习
Markdown笔记 :done, des1, 2025-04-01, 3d
Tmux配置 :active, des2, 2025-04-04, 2d
Mermaid学习 : des3, 2025-04-06, 4d
section 项目实战
个人博客搭建 : des4, after des3, 5d
部署上线 : des5, 2025-04-15, 2d常用配置项：
title：图表标题dateFormat：日期格式，常用YYYY-MM-DDsection：分组- 任务行：
任务名 : 状态, 任务ID, 开始日期, 持续时间 - 状态：
done（已完成）、active（进行中）、crit（关键任务，红色高亮）、无状态（未开始） - 开始日期：可以用具体日期
2025-04-01，也可以用after 任务ID表示依赖 - 持续时间：
Xd（X天）、Xw（X周）、Xm（X月）
自定义日期格式：
dateFormat YYYY-MM-DD
axisFormat %m-%d # X轴显示格式实战示例：找工作复习计划：
gantt
title 求职准备甘特图
dateFormat YYYY-MM-DD
section 算法
刷LeetCode 100题 :active, algo1, 2025-04-01, 15d
复习动态规划专题 :algo2, after algo1, 5d
section 系统设计
阅读DDIA前三章 :sd1, 2025-04-01, 10d
画5个高频系统设计图 :sd2, after sd1, 7d
section 简历与投递
更新简历 :crit, resume1, 2025-04-10, 2d
海投 :resume2, after resume1, 10d我的用法：每个月初画一张甘特图，贴在当月笔记的最前面，月底复盘对照进度。甘特图的文本描述比 Excel 轻量太多了。
4. 类图（Class Diagram）
适合画面向对象设计、数据库实体关系、系统模块结构。
classDiagram
class 用户 {
+string 用户名
-string 密码
+登录()
-验证()
}
class 订单 {
+int 订单号
+日期 创建时间
+创建订单()
}
用户 "1" --> "0..*" 订单 : 拥有可见性符号：
+public-private#protected~package/internal
关系类型：
| 符号 | 含义 |
|---|---|
<|-- | 继承（子类指向父类） |
*-- | 组合（强聚合） |
o-- | 聚合（弱聚合） |
--> | 关联 |
..> | 依赖 |
..|> | 实现接口 |
实战示例：博客系统实体关系：
classDiagram
class 文章 {
+int id
+string title
+string content
+datetime createTime
+发布()
+编辑()
}
class 用户 {
+int id
+string name
+string email
+写文章()
}
class 分类 {
+int id
+string name
}
用户 "1" --> "0..*" 文章 : 撰写
文章 "*" --> "1" 分类 : 属于类图我不常用，但在设计数据库表结构或者理解开源项目时非常有用。我一般先画类图再建表，能直观看到实体间的关联。
5. 状态图（State Diagram）
描述一个对象在其生命周期中的状态变化。
stateDiagram-v2
[*] --> 待支付
待支付 --> 已支付 : 支付成功
待支付 --> 已取消 : 超时/用户取消
已支付 --> 已发货 : 商家发货
已发货 --> 已完成 : 确认收货
已发货 --> 退款中 : 申请退款
退款中 --> 已退款
已完成 --> [*]
已取消 --> [*]
已退款 --> [*]状态图 v2 语法更简洁，推荐使用 stateDiagram-v2。
带条件的状态转换：
stateDiagram-v2
[*] --> 审核
审核 --> 通过 : 条件：分数 >= 60
审核 --> 不通过 : 条件：分数 < 606. 饼图（Pie Chart）
简单直观的数据比例展示。
pie title 每天时间分配
"睡眠" : 8
"工作" : 9
"学习" : 2
"通勤" : 1.5
"娱乐" : 3.57. 用户旅程图（User Journey）
适合产品设计、用户体验分析。
journey
title 用户购买流程体验
section 浏览商品
搜索商品: 5: 用户
查看详情: 4: 用户
加入购物车: 3: 用户
section 结算
填写地址: 2: 用户
选择支付: 4: 用户
完成支付: 5: 用户8. Git 图（Gitgraph）
展示 Git 分支和提交历史。
gitGraph
commit
branch feature
checkout feature
commit
commit
checkout main
merge feature四、高阶技巧与踩坑记录
1. 特殊字符转义
节点文本中的 ()、[]、{}、<> 等特殊符号可能需要转义或用引号包裹：
graph TD
A["这是一个包含括号(的文本"]
B["文本中的<>符号"]2. 多行文本
用 <br> 或双反斜杠 \\ 换行（取决于渲染器）：
graph TD
A["第一行<br>第二行<br>第三行"]3. 自定义样式
可以用 style 语句修改节点样式（部分渲染器支持有限）：
graph TD
A[开始]
style A fill:#f9f,stroke:#333,stroke-width:2px4. 注释
Mermaid 没有官方注释语法，但可以用 HTML 注释 <!-- --> 包裹整行（在代码块中可能不生效），或者用 %%（部分版本支持）。我一般不加注释，保持简洁。
5. 跨平台渲染差异
- GitHub：支持大部分图表，但
stateDiagram-v2和journey支持不稳定，建议用stateDiagram。 - GitLab：支持较好。
- Obsidian：需要安装 Mermaid 插件，支持度很好。
- VS Code 预览：推荐用
Markdown Preview Mermaid Support插件。
踩坑：在 GitHub 上用
sequenceDiagram时，activate和deactivate有时候渲染错位，可以用+/-简写代替。另外，alt块里的缩进必须严格一致，否则解析失败。
五、高频使用场景
场景 1：技术方案设计
画流程图描述核心逻辑，用时序图画接口调用顺序，最后用类图画模块关系。三个图放在同一个笔记里，方案就非常清晰了。
场景 2：算法学习笔记
graph LR
A[排序算法] --> B[比较排序]
A --> C[非比较排序]
B --> D[快速排序]
B --> E[归并排序]
B --> F[堆排序]
C --> G[计数排序]
C --> H[基数排序]场景 3：故障复盘
用时序图画出现问题的请求链路，标注出失败的点。
场景 4：学习计划管理
每月一张甘特图，贴在月计划笔记的开头。每周回顾时更新进度（把 done 状态标上）。
六、速查表
| 图表类型 | 代码块标识 | 常用场景 |
|---|---|---|
| 流程图 | graph TD/LR | 流程、逻辑、架构 |
| 时序图 | sequenceDiagram | 交互、API、消息 |
| 甘特图 | gantt | 项目排期、学习计划 |
| 类图 | classDiagram | 面向对象设计、数据库ER |
| 状态图 | stateDiagram-v2 | 状态机、生命周期 |
| 饼图 | pie | 数据占比 |
| 用户旅程图 | journey | 产品体验 |
| Git图 | gitGraph | 版本分支可视化 |
流程图节点形状速记：
[矩形]普通步骤(圆角)通常表示开始/结束的替代{菱形}判断分支((圆形))起点/终点[(圆柱)]数据库{{六边形}}准备/预处理
时序图消息符号速记：
->>实线箭头-->>虚线箭头+)激活生命线-)结束生命线
作者
884705373@qq.com
相关文章
