【Mermaid】5 分钟掌握 Mermaid:从流程图到时序图,一篇文章搞定技术文档可视化全场景
写技术方案时对着空白文档抓耳挠腮?画流程图还在靠 PPT 拖曳矩形框?写接口文档时时序图总被吐槽「灵魂画风」?作为程序员 / 产品经理 / 技术作者,你是否也被「文档可视化」狠狠拿捏过?现在,只需,就能用代码直接生成高颜值流程图、时序图、甘特图 —— 无需安装复杂绘图软件,无需手动调整格式,甚至能无缝嵌入 Markdown 文档,让技术方案瞬间「图文并茂」。从入门语法到实战模板,本文覆盖,带你
5 分钟掌握 Mermaid:从流程图到时序图,一篇文章搞定技术文档可视化全场景
写技术方案时对着空白文档抓耳挠腮?画流程图还在靠 PPT 拖曳矩形框?写接口文档时时序图总被吐槽「灵魂画风」?作为程序员 / 产品经理 / 技术作者,你是否也被「文档可视化」狠狠拿捏过?
现在,只需5 分钟掌握 Mermaid 语法,就能用代码直接生成高颜值流程图、时序图、甘特图 —— 无需安装复杂绘图软件,无需手动调整格式,甚至能无缝嵌入 Markdown 文档,让技术方案瞬间「图文并茂」。从入门语法到实战模板,本文覆盖90% 技术文档绘图场景,带你从「绘图苦手」变身「可视化达人」。
一、1分钟配置Mermaid使用环境
无论你是用本地编辑器写文档、在在线平台发布内容,还是在 Web 项目中集成图表,Mermaid 都能零门槛启动。按场景划分配置步骤,1 分钟内搞定所有准备工作:
1. 本地 Markdown 编辑器(以 Typora 为例)—— 30 秒启用可视化
✅ 操作步骤:
① 打开 Typora → 点击顶部菜单 文件 → 偏好设置(快捷键 Ctrl+, / Cmd+,)
② 在左侧「Markdown」设置中,找到 「Mermaid 图表」 选项并勾选(默认未启用)
③ 关闭设置窗口,直接输入 Mermaid 代码块即可实时渲染:
▶️ 效果:输入完成后,Typora 会实时将代码渲染为流程图,无需手动刷新或安装额外插件。
2. 在线平台(CSDN/GitHub/Jira 等)—— 零配置直出图表
这类平台已原生支持 Mermaid 语法,无需任何设置,直接按标准 Markdown 语法编写即可:
▶️ 适用场景:
- 技术博客(CSDN / 知乎):在 Markdown 编辑器中插入 mermaid 代码块,发布后自动渲染为图表。
-
项目文档(GitHub README):提交代码时直接包含 Mermaid 代码,仓库页面会实时显示架构图 / 流程图。
-
团队协作(Jira/Notion):支持代码块格式,需求文档中的时序图 / 甘特图可直接被团队成员查看。
3. Web 开发场景(JS 集成)—— 5 分钟嵌入网页
若需在 Web 项目中动态生成图表(如数据可视化后台、技术文档网站),可通过 JavaScript 集成 Mermaid:
✅ 步骤 1:引入 Mermaid 脚本
<!-- 引入最新版 Mermaid(CDN 方式,无需下载) -->
<script src="https://cdn.jsdelivr.net/npm/mermaid@10.4.0/dist/mermaid.min.js"></script>
<!-- 初始化配置(可选,自定义主题/样式) -->
<script>
mermaid.initialize({
theme: "neutral", // 主题:默认、深色、浅色、中性
startOnLoad: true // 加载后自动渲染图表
});
</script>
✅ 步骤 2:在 HTML 中插入 Mermaid 代码块
<div class="mermaid">
```mermaid
graph LR
A[用户操作] --> B{业务逻辑判断}
B -->|成功| C[写入数据库]
B -->|失败| D[返回错误提示]
✅ 效果:
浏览器加载页面时,会自动将代码块渲染为交互式图表,支持点击节点查看细节(需 Mermaid 交互功能开启)。
🔧 核心配置逻辑对比
使用场景 | 核心步骤 | 关键代码标识 | 额外依赖 |
---|---|---|---|
本地编辑器 | 勾选功能选项 | mermaid 代码块 | Typora/Obsidian 原生支持 |
在线平台 | 直接编写代码 | 同上 | 平台内置 Mermaid 解析器 |
Web 开发(JS) | 引入脚本 + 代码块包裹 | Mermaid CDN 或本地脚本 |
🛠️ 配置常见问题(5 秒自查)
问题现象 | 解决方案 |
---|---|
Typora 图表不显示 | 1. 检查「偏好设置 → Markdown」中是否勾选「Mermaid 图表」2. 重启 Typora 生效 |
在线平台渲染乱码 | 确认代码块以 mermaid 严格包裹,避免中英文括号混用(如用 [] 而非 【】) |
JS 集成后图表不加载 | 1. 检查 Mermaid 脚本 URL 是否正确2. 确保代码块在
标签内
|
完成环境配置后,接下来进入 「3 分钟掌握核心语法」 环节,从最常用的流程图开始,带你用代码「画」出第一个可视化图表!
二、3 分钟掌握核心语法:18 类图表快速上手
Mermaid 语法遵循「关键词 + 结构化描述」逻辑,掌握核心关键词即可覆盖 90% 绘图场景。以下按高频场景分类,代码案例单独展示,附最简语法和配置说明:
1. 流程图(Flowchart)
适用场景:业务逻辑、算法步骤、工作流程可视化
语法核心:graph
+ 节点关系(->
/-->
/-.->
)
节点类型:[方形]
/(圆角)
/{菱形}
/>旗帜形]
代码示例
graph TD
A[用户登录] --> B{权限验证}
B -->|管理员| C[进入管理后台]
B -->|普通用户| D[进入个人中心]
C --> E[数据管理]
D --> E[查看订单]
配置参数:
-
graph TD
:布局方向(TD
上下 |LR
左右 |BT
下上 |RL
右左) -
style 节点名 fill:#颜色,stroke:#颜色
:自定义样式(例:style B fill:#ffd700
金色背景)
2. 时序图(Sequence Diagram)
适用场景:接口调用流程、系统交互逻辑、消息传递顺序
语法核心:sequenceDiagram
+ 参与者 + 消息流向(->>
/-->>
)
代码示例
sequenceDiagram
participant 客户端
participant 服务器
participant 数据库
客户端->>服务器: 发送查询请求
服务器->>数据库: 执行SQL查询
数据库-->>服务器: 返回数据
服务器-->>客户端: 返回查询结果
配置参数:
-
participant
:显式定义参与者(可省略,直接用名称) -
note left/right of 节点: 文本
:添加注释(例:note right of 服务器: 调用Redis缓存
)
3. 类图(Class Diagram)
适用场景:面向对象设计、系统架构建模、类关系展示
语法核心:classDiagram
+ 继承(<|--
)/ 实现(--|>
)/ 关联(--
)
代码示例
classDiagram
class 动物 {
+string name
+void eat()
}
class 鸟类 {
+float wingSpan
+void fly()
}
动物 <|-- 鸟类
鸟类 --|> 飞行动物接口
配置参数:
-
成员修饰符:
+
(公共)、-
(私有)、#
(保护)、~
(包可见) -
class 类名 #颜色
:设置背景色(例:class 动物 #lightblue
浅蓝色背景)
4. 状态图(State Diagram)
适用场景:系统状态转换、流程状态机、设备生命周期
语法核心:stateDiagram
+ 状态节点([*]
表示初始 / 结束状态)
代码示例
stateDiagram
[*] --> 空闲状态
空闲状态 --> 处理请求: 接收到任务
处理请求 --> 完成状态: 任务执行完毕
完成状态 --> [*]: 重置系统
配置参数:
-
[*]
:必须包含初始状态(单个),结束状态可多个([*]
) -
state 状态名 <<类型>>
:定义状态类别(例:state 处理请求 <<running>>
)
5. 甘特图(Gantt Chart)
适用场景:项目进度管理、任务排期、资源分配
语法核心:gantt
+ dateFormat
+ 任务分段
代码示例
gantt
title 产品迭代计划
dateFormat YYYY-MM
section 开发阶段
需求分析 :a1, 2023-01, 30d
架构设计 :a2, after a1, 20d
编码实现 :a3, after a2, 60d
section 测试阶段
单元测试 :a4, after a3, 20d
集成测试 :a5, after a4, 15d
配置参数:
-
dateFormat
:支持YYYY-MM-DD
/Q1
等格式(例:dateFormat Q - YYYY
季度显示) -
section
:任务分组(可通过 CSS 自定义组颜色)
6. 饼图(Pie Chart)
适用场景:数据占比分析、资源分布展示(需 Mermaid 9.4+)
语法核心:pie
+ title
+ 数据项
代码示例
---
config:
pie:
textPosition: 0.5
themeVariables:
pieOuterStrokeWidth: "2px"
---
pie title 浏览器市场份额
"Chrome" : 43.89
"Edge" : 16.13
"Safari" : 15.22
"其他" : 24.76
---
config:
pie:
textPosition: 0.5
themeVariables:
pieOuterStrokeWidth: "2px"
---
pie title 浏览器市场份额
"Chrome" : 43.89
"Edge" : 16.13
"Safari" : 15.22
"其他" : 24.76
配置参数:
-
数据项直接跟数值(自动计算百分比,总和需 > 0)
-
click
:绑定点击事件(需 JS 集成,例:click "Chrome" "``https://chrome.com``"
)
7. GitGraph(Git 提交历史)
适用场景:代码分支管理、版本控制可视化
语法核心:gitGraph
+ 分支(branch
)+ 提交(commit
)
代码示例
---
title: Example Git diagram
---
gitGraph
commit
commit
branch develop
checkout develop
commit
commit
checkout main
merge develop
commit
commit
---
title: Example Git diagram
---
gitGraph
commit
commit
branch develop
checkout develop
commit
commit
checkout main
merge develop
commit
commit
配置参数:
-
branch
:创建分支(例:branch hotfix/v1
带版本号分支) -
commit
:提交描述(支持多行,用"""
包裹)
8. 思维导图(Mind Map)
适用场景:知识体系梳理、脑暴创意发散(用流程图模拟树状结构)
语法核心:graph TD
+ 子节点缩进
代码示例
graph TD
A[核心主题] --> B1[子主题1]
A --> B2[子主题2]
B2 --> C1[子子主题1]
B2 --> C2[子子主题2]
配置参数:
-
节点形状:默认方形,圆形用
(子主题)
,菱形用{子主题}
-
rankdir
:布局方向(例:graph LR
横向扩展)
9. 时间线图(Timeline)
适用场景:历史事件排序、项目里程碑展示(Mermaid 8.11+ 支持)
语法核心:timeline
+ 时间分区(section
)
代码示例
timeline
title 技术演进史
section 2000s
2004 : HTML5 草案发布
2008 : Chrome 浏览器诞生
section 2010s
2014 : ES6 标准确立
2019 : WebAssembly 正式发布
timeline
title 技术演进史
section 2000s
2004 : HTML5 草案发布
2008 : Chrome 浏览器诞生
section 2010s
2014 : ES6 标准确立
2019 : WebAssembly 正式发布
配置参数:
-
时间格式:支持
YYYY
/YYYY-MM
/YYYY-MM-DD HH:mm
-
section
:按时间区间分组(可自定义标题样式)
10. 桑基图(Sankey Diagram)
适用场景:能量流动、资源分配、数据流向分析(Mermaid 10.0+ 支持)
语法核心:sankey
+ 节点 + 链接(->
带数值)
代码示例
---
config:
sankey:
showValues: false
---
sankey-beta
Agricultural 'waste',Bio-conversion,124.729
Bio-conversion,Liquid,0.597
Bio-conversion,Losses,26.862
Bio-conversion,Solid,280.322
Bio-conversion,Gas,81.144
Biofuel imports,Liquid,35
Biomass imports,Solid,35
Coal imports,Coal,11.606
Coal reserves,Coal,63.965
Coal,Solid,75.571
District heating,Industry,10.639
District heating,Heating and cooling - commercial,22.505
District heating,Heating and cooling - homes,46.184
Electricity grid,Over generation / exports,104.453
Electricity grid,Heating and cooling - homes,113.726
Electricity grid,H2 conversion,27.14
Electricity grid,Industry,342.165
Electricity grid,Road transport,37.797
Electricity grid,Agriculture,4.412
Electricity grid,Heating and cooling - commercial,40.858
Electricity grid,Losses,56.691
Electricity grid,Rail transport,7.863
Electricity grid,Lighting & appliances - commercial,90.008
Electricity grid,Lighting & appliances - homes,93.494
Gas imports,Ngas,40.719
Gas reserves,Ngas,82.233
Gas,Heating and cooling - commercial,0.129
Gas,Losses,1.401
Gas,Thermal generation,151.891
Gas,Agriculture,2.096
Gas,Industry,48.58
Geothermal,Electricity grid,7.013
H2 conversion,H2,20.897
H2 conversion,Losses,6.242
H2,Road transport,20.897
Hydro,Electricity grid,6.995
Liquid,Industry,121.066
Liquid,International shipping,128.69
Liquid,Road transport,135.835
Liquid,Domestic aviation,14.458
Liquid,International aviation,206.267
Liquid,Agriculture,3.64
Liquid,National navigation,33.218
Liquid,Rail transport,4.413
Marine algae,Bio-conversion,4.375
Ngas,Gas,122.952
Nuclear,Thermal generation,839.978
Oil imports,Oil,504.287
Oil reserves,Oil,107.703
Oil,Liquid,611.99
Other waste,Solid,56.587
Other waste,Bio-conversion,77.81
Pumped heat,Heating and cooling - homes,193.026
Pumped heat,Heating and cooling - commercial,70.672
Solar PV,Electricity grid,59.901
Solar Thermal,Heating and cooling - homes,19.263
Solar,Solar Thermal,19.263
Solar,Solar PV,59.901
Solid,Agriculture,0.882
Solid,Thermal generation,400.12
Solid,Industry,46.477
Thermal generation,Electricity grid,525.531
Thermal generation,Losses,787.129
Thermal generation,District heating,79.329
Tidal,Electricity grid,9.452
UK land based bioenergy,Bio-conversion,182.01
Wave,Electricity grid,19.013
Wind,Electricity grid,289.366
---
config:
sankey:
showValues: false
---
sankey-beta
Agricultural 'waste',Bio-conversion,124.729
Bio-conversion,Liquid,0.597
Bio-conversion,Losses,26.862
Bio-conversion,Solid,280.322
Bio-conversion,Gas,81.144
Biofuel imports,Liquid,35
Biomass imports,Solid,35
Coal imports,Coal,11.606
Coal reserves,Coal,63.965
Coal,Solid,75.571
District heating,Industry,10.639
District heating,Heating and cooling - commercial,22.505
District heating,Heating and cooling - homes,46.184
Electricity grid,Over generation / exports,104.453
Electricity grid,Heating and cooling - homes,113.726
Electricity grid,H2 conversion,27.14
Electricity grid,Industry,342.165
Electricity grid,Road transport,37.797
Electricity grid,Agriculture,4.412
Electricity grid,Heating and cooling - commercial,40.858
Electricity grid,Losses,56.691
Electricity grid,Rail transport,7.863
Electricity grid,Lighting & appliances - commercial,90.008
Electricity grid,Lighting & appliances - homes,93.494
Gas imports,Ngas,40.719
Gas reserves,Ngas,82.233
Gas,Heating and cooling - commercial,0.129
Gas,Losses,1.401
Gas,Thermal generation,151.891
Gas,Agriculture,2.096
Gas,Industry,48.58
Geothermal,Electricity grid,7.013
H2 conversion,H2,20.897
H2 conversion,Losses,6.242
H2,Road transport,20.897
Hydro,Electricity grid,6.995
Liquid,Industry,121.066
Liquid,International shipping,128.69
Liquid,Road transport,135.835
Liquid,Domestic aviation,14.458
Liquid,International aviation,206.267
Liquid,Agriculture,3.64
Liquid,National navigation,33.218
Liquid,Rail transport,4.413
Marine algae,Bio-conversion,4.375
Ngas,Gas,122.952
Nuclear,Thermal generation,839.978
Oil imports,Oil,504.287
Oil reserves,Oil,107.703
Oil,Liquid,611.99
Other waste,Solid,56.587
Other waste,Bio-conversion,77.81
Pumped heat,Heating and cooling - homes,193.026
Pumped heat,Heating and cooling - commercial,70.672
Solar PV,Electricity grid,59.901
Solar Thermal,Heating and cooling - homes,19.263
Solar,Solar Thermal,19.263
Solar,Solar PV,59.901
Solid,Agriculture,0.882
Solid,Thermal generation,400.12
Solid,Industry,46.477
Thermal generation,Electricity grid,525.531
Thermal generation,Losses,787.129
Thermal generation,District heating,79.329
Tidal,Electricity grid,9.452
UK land based bioenergy,Bio-conversion,182.01
Wave,Electricity grid,19.013
Wind,Electricity grid,289.366
配置参数:
-
node
:显式定义节点(可省略,直接在link
中使用名称) -
链接数值:决定线条粗细(数值越大,线条越粗)
11. 架构图(Architecture Diagram)
适用场景:系统分层设计、微服务架构展示(组合流程图 + 类图)
语法核心:graph LR
+ 分组(subgraph
)
代码示例
graph LR
subgraph 前端层
A[Web 端]
B[移动端]
end
subgraph 服务层
C[API 网关]
D[用户服务]
E[订单服务]
end
A --> C
B --> C
C --> D
C --> E
配置参数:
-
subgraph
:分组定义(例:subgraph title 核心服务
带标题分组) -
style subgraph fill:#f5f5f5
:设置分组背景色(浅灰色)
12. 雷达图(Radar Chart)
适用场景:多维数据对比、性能指标分析(需结合外部库,Mermaid 原生不支持)
替代方案代码示例(用流程图模拟框架):
graph TD
style A fill:none,stroke:#333,stroke-width:2px
A((维度1)) --> B((维度2)) --> C((维度3)) --> D((维度4)) --> A
注意:Mermaid 无原生雷达图语法,建议导出 SVG 后用工具编辑,或集成 ECharts/Highcharts。
🔧 通用配置参数速查表
功能 | 语法示例 | 说明 |
---|---|---|
全局主题 | mermaid<br>%%{init: {theme: "dark"}}%%<br>graph TD... |
支持 default /dark /neutral /light 四种主题 |
字体设置 | mermaid<br>%%{init: {fontFamily: "微软雅黑"}}%%<br>... |
需编辑器支持预处理指令(如 Typora/VS Code) |
交互链接 | click 节点名 "https://url" "新窗口" |
点击节点跳转(在线平台可能禁用 JavaScript 交互) |
图表尺寸 | <div style="max-width: 600px;"><br> mermaid…</div> |
通过 HTML 包裹自定义容器宽度 |
掌握以上核心语法后,90% 的技术文档绘图需求都能轻松实现。下一节将带来 「5 个实战模板」,涵盖需求文档、架构设计、项目复盘等高频场景,直接复制即可套用!
三、5 个实战模板:高频场景快速套用
掌握核心语法后,直接套用以下模板解决实际绘图需求,代码可直接复制到文档中使用:
模板 1:需求文档 - 业务流程 + 接口交互
适用场景:需求评审、功能说明文档
核心图表:流程图 + 时序图
代码示例
### 业务流程图
graph TD
A[用户下单] --> B{库存校验}
B -->|充足| C[生成订单]
B -->|不足| D[触发补货流程]
C --> E[发送支付请求]
D --> E
E --> F[支付回调处理]
F --> G[订单状态更新]
### 接口调用图
sequenceDiagram
participant 用户端
participant 订单服务
participant 支付网关
用户端->>订单服务: 提交订单(含商品ID)
订单服务->>支付网关: 调用支付接口(金额/订单号)
支付网关-->>订单服务: 返回支付结果(成功/失败)
订单服务-->>用户端: 返回订单状态
使用说明:
-
流程图标注业务分支逻辑(库存校验),时序图明确接口调用参数
-
可添加
note
注释(如note right of 订单服务: 记录操作日志
)
模板 2:架构设计 - 系统分层 + 模块依赖
适用场景:技术方案文档、架构说明书
核心图表:架构图 + 类图
代码示例
### 分层架构图
graph LR
subgraph 用户层
Web[Web 控制台]
App[移动端App]
end
subgraph 服务层
Gateway[API网关]
subgraph 核心服务
User[用户中心]
Order[订单中心]
Payment[支付中心]
end
end
subgraph 数据层
DB[关系型数据库]
Cache[Redis缓存]
end
Web --> Gateway
App --> Gateway
Gateway --> User
Gateway --> Order
User --> DB
Order --> DB
Order --> Cache
### 核心类图
classDiagram
class OrderService {
+createOrder()
+queryOrder()
}
class PaymentService {
+pay()
+refund()
}
OrderService --|> BaseService
PaymentService --|> BaseService
OrderService "1" -- "n" PaymentService
使用说明:
-
subgraph
区分系统层级,classDiagram
展示核心类关系 -
用
style subgraph fill:#ebf5fb
设置浅色背景突出分层
模板 3:项目复盘 - 进度追踪 + 里程碑
适用场景:项目总结报告、迭代复盘文档
核心图表:甘特图 + 时间线图
代码示例
### 进度甘特图
gantt
title Q3项目进度复盘
dateFormat YYYY-MM-DD
section 开发阶段
需求分析 :done, a1, 2023-07-01, 15d
开发实现 :done, a2, 2023-07-16, 45d
联调测试 :active, a3, 2023-09-01, 30d
section 发布阶段
灰度发布 :a4, 2023-09-30, 10d
全量上线 :a5, 2023-10-10, 5d
### 里程碑时间线
timeline
title 项目关键节点
section 启动阶段
2023-07-01 : 需求评审通过
section 攻坚阶段
2023-08-15 : 核心模块联调完成
2023-09-05 : 第一轮压测通过
section 收尾阶段
2023-10-15 : 项目结项验收
timeline
title 项目关键节点
section 启动阶段
2023-07-01 : 需求评审通过
section 攻坚阶段
2023-08-15 : 核心模块联调完成
2023-09-05 : 第一轮压测通过
section 收尾阶段
2023-10-15 : 项目结项验收
使用说明:
-
甘特图用
done/active
标注任务状态,时间线按阶段分组 -
搭配
dateFormat Q - YYYY
可按季度展示(如2023-Q3
)
模板 4:接口设计 - 调用流程 + 异常处理
适用场景:API 文档、微服务交互说明
核心图表:时序图(含异常分支)
代码示例
使用说明:
-
alt
语法标注异常分支(Token 无效 / 数据库超时) -
消息箭头用
->>
(同步)/-->>
(异步)区分调用类型
模板 5:数据可视化 - 占比分析 + 流向追踪
适用场景:数据报告、资源分析文档
核心图表:饼图 + 桑基图
代码示例
### 资源占比饼图
pie title 服务器资源占用
"CPU" : 35
"内存" : 25
"磁盘IO" : 20
"网络" : 20
### 数据流向桑基图
sankey-beta
%% source,target,value
MainPage,GoodsPage,80
GoodsPage,Cart,30
GoodsPage,PaymentPage,10
Cart,PaymentPage,20
sankey-beta
%% source,target,value
MainPage,GoodsPage,80
GoodsPage,Cart,30
GoodsPage,PaymentPage,10
Cart,PaymentPage,20
使用说明:
-
饼图直接输入数值(自动计算百分比),桑基图数值代表流量大小
-
搭配
%%{init: {theme: "neutral"}}%%
使用中性主题提升可读性
模板使用技巧
-
快速替换:复制代码后,直接修改节点名称、参数和注释,5 分钟生成定制图表
-
多图组合:在文档中并列多个图表(如需求文档同时放流程图 + 时序图)
-
导出图片:在 Typora 中右键图表→导出为 PNG,插入非 Markdown 文档(如 Word/PDF)
通过以上模板,无需重复编写基础语法,聚焦业务逻辑即可高效完成技术文档可视化。下一节将解答 「常见问题与避坑指南」,帮你解决图表渲染异常、语法报错等实战问题!
更多推荐
所有评论(0)