夜雨聆风
AI也能画图-认识 Mermaid:让文档自己画图的
01 认识 Mermaid：让文档自己画图的「文本即图形」引擎
在软件需求、技术方案、会议纪要里，流程图、时序图几乎是标配。传统做法需要打开 Visio、draw.io 或 PowerPoint 手动拖拽，不仅耗时，而且版本管理困难、协作成本高。
Mermaid 把“画图”这件事变成了“写文档”——只要在 Markdown 里写几行类 Markdown 的文本，就能自动渲染出可交互、可搜索、可版本控制的矢量图。它的意义可以概括为：
-
低心智负担：纯文本，无 UI 操作； -
可版本化：图就是代码，diff 清晰可见； -
自动化：结合 CI/CD 可以在文档、Wiki、Slide 中自动生成最新图； -
生态成熟：GitHub、GitLab、Notion、Obsidian、VS Code 均已原生或插件支持。
02 Mermaid 语法总览
Mermaid 语法由“声明块 + 图类型 + 图描述”三部分构成，最简模板如下：
渲染结果：
graph TD
A[开始] --> B{条件}
B -->|true| C[处理]
B -->|false| D[结束]
03 核心功能与实战示例
下面按场景拆分，逐一枚举常用功能，并给出可直接复制运行的代码。
03-1 Flowchart（流程图）
功能点
-
方向控制（TD/LR/RL/BT） -
节点形状（矩形、圆角、圆形、子图、数据库） -
连线样式（实线、虚线、箭头、无箭头、加粗） -
子图（subgraph）实现嵌套布局
示例：订单状态机
渲染结果：
flowchart TD
S([开始]) --> P[待支付] -->|支付成功| W{库存检查}
W -->|有货| A[已发货]
W -->|缺货| C[退款中]
C --> E([结束])
A --> E
subgraph 物流子流程
A --> T[拣货] --> D[配送]
end
classDef green fill:#c2e0c6,stroke:#006100
classDef red fill:#f2b3b3,stroke:#c5504b
class A green
class C red
解读
-
([ ])圆形节点；{ }菱形判断；[ ]矩形。 -
classDef自定义颜色，配合class语句批量着色。 -
subgraph关键字创建可折叠区域，便于大型流程分层展示。
03-2 Sequence Diagram（时序图）
功能点
-
Actor / Participant 声明 -
同步/异步消息（ ->,-->>） -
激活条（ activate、deactivate） -
循环（loop）、可选（opt）、并行（par）片段
示例：OAuth2 授权码流程
渲染结果：
sequenceDiagram
participant U as 用户浏览器
participant A as 前端 App
participant S as 授权服务器
participant R as 资源服务器
U->>A: 点击登录
A->>U: 302 重定向到 /authorize
U->>S: 登录并同意授权
S->>U: 302 返回 code
U->>A: 携带 code 回前端
A->>S: POST /token code+secret
activate S
S-->>A: 返回 access_token
deactivate S
A->>R: GET /userinfo
activate R
R-->>A: 返回用户信息
deactivate R
解读
-
participant X as 别名解决中文或长名问题。 -
activate/deactivate生成激活条，突出耗时操作。 -
-->>虚线箭头表示异步返回。
03-3 Gantt（甘特图）
功能点
-
任务、里程碑、章节分组 -
日期格式、工作日历 -
关键路径高亮
示例：两周 Sprint 计划
渲染结果：
gantt
title Sprint 25 甘特图（修正版 1）
dateFormat YYYY-MM-DD
excludes weekends
section 需求
需求澄清 :a1, 2025-08-18, 2d
section 开发
接口设计 :dev1, after a1, 1d
前端开发 :dev2, after dev1, 3d
后端开发 :dev3, after dev1, 3d
section 测试
联调 :t1, after dev2, 1d
回归测试 :t2, after t1, 1d
上线 :milestone, m1, after t2, 0d
解读
-
after 任务名建立依赖，自动计算开始时间。 -
excludes weekends排除周末，甘特条会自动跳过。 -
milestone零耗时节点，常用于发布节点。
03-4 Class Diagram（类图）
功能点
-
类、接口、枚举、包 -
可见性（+ public、- private、# protected） -
关系：继承（<|–）、组合（*–）、聚合（o–）、关联（–>）
示例：电商核心域模型
渲染结果：
classDiagram
class Customer {
-String id
-String name
+register()
}
class Order {
-String orderNo
-BigDecimal amount
+pay()
}
class Product {
-String sku
-int stock
+reduceStock()
}
class OrderItem {
-int quantity
}
Customer "1" --> "*" Order : places
Order "1" *-- "*" OrderItem : contains
OrderItem "*" --> "1" Product : refers
解读
-
"1" --> "*"表示一对多关联，语义与 UML 一致。 -
*--实心菱形代表强聚合（整体-部分生命周期一致）。
03-5 State Diagram（状态机）
功能点
-
状态、转移、开始/结束节点 -
并发状态（fork/join）
示例：工单状态
渲染结果：
stateDiagram-v2
[*] --> New
New --> Assigned : 分派
Assigned --> Processing : 开始处理
Processing --> Resolved : 修复
Resolved --> Closed : 客户确认
Resolved --> Reopened : 未解决
Reopened --> Processing
Closed --> [*]
03-6 Pie Chart（饼图）
pie title 本月服务器错误分布
"5xx" : 42
"4xx" : 28
"Timeout" : 15
"Network" : 9
"Other" : 6
03-7 Requirement Diagram（需求追踪）
需求图可追溯到测试用例，适合 MBSE（基于模型的系统工程）。
requirementDiagram
requirement req {
id: 1
text: 用户登录时间 ≤ 2 秒
risk: high
verifymethod: test
}
test_case tc {
id: TC-01
title: 登录性能测试
}
req - traces -> tc
04 进阶技巧
-
主题与自定义样式：
Mermaid 内置 7 套主题（default、dark、forest、neutral、base、darkMode、base），也支持覆盖 CSS 变量。%%{init:{'theme':'dark'}}%% -
CLI & CI 集成：
安装@mermaid-js/mermaid-cli，可在 GitHub Actions 中把.mmd文件批量转成.svg或.png，并上传到文档站点。 -
VS Code 插件：
插件 “Markdown Preview Mermaid Support” 支持实时预览，断点调试语法。 -
PlantUML 迁移：
用mermaid-to-plantuml反向转换，或利用mermaid-zenuml输出更符合中文习惯的时序图。
05 总结
-
Mermaid 把“图”纳入源码管理，极大降低了维护成本。 -
支持 10+ 种图类型，覆盖需求、架构、排期、运维指标等全链路场景。 -
语法简洁，生态工具链完备，从本地 Markdown 预览到线上自动化文档，全流程无缝。 -
对于团队写作、Code Review、技术博客，Mermaid 都是“写一次，到处渲染”的利器。
下次写文档时，不妨先敲几行 Mermaid，让图“自己长出来”。Happy diagramming!
