Mermaid 使用手册

一、Mermaid 概述

Mermaid 是基于 JavaScript 的文本驱动图表生成工具，采用类 Markdown 语法，可动态渲染、跨平台兼容，支持在 Markdown 编辑器、在线平台、Web 项目中直接使用。

支持图表类型

流程图、时序图、类图、状态图、甘特图、饼图、实体关系图、用户旅行图、Git 图、时间线图、桑基图、架构图

使用方式

1. 本地 Markdown 编辑器：Typora、Obsidian、VS Code 等，开启 Mermaid 支持即可实时渲染
2. 在线平台：GitHub、CSDN、Notion、Jira 等原生支持，直接编写代码块
3. Web 开发：通过 CDN 引入 Mermaid 脚本，初始化后自动渲染
4. 命令行工具：生成 SVG、PNG 格式图片

二、流程图（Flowchart）

适用场景

业务流程、算法步骤、工作流、系统逻辑梳理

基础语法

graph <方向>
节点定义
节点连线

布局方向

• TB：从上到下（默认）
• BT：从下到上
• LR：从左到右
• RL：从右到左

节点类型

节点形状	语法	用途
矩形	id[文字]	普通步骤
圆角矩形	id(文字)	起止/常规步骤
体育场形	id([文字])	特殊步骤
子程序形	id[[文字]]	子流程
圆柱形	id[(文字)]	数据存储/数据库
圆形	id((文字))	开始/结束
菱形	id{文字}	条件判断
六边形	id{{文字}}	事件/过程
平行四边形	id[/文字/]	输入
反向平行四边形	id[\文字\]	输出

连线样式

• 实线：A --> B
• 粗实线：A ==> B
• 虚线：A -.-> B
• 无箭头线：A --- B
• 双向箭头：A <--> B
• 带文字连线：A -->|条件| B

高级用法

1. 并行节点：B & C --> D
2. 子图：

graph LR
subgraph 子图名称[子图标题]
direction LR
节点1 --> 节点2
end
A --> 子图名称 --> B

示例

graph LR
A[开始] --> B{订单有效?}
B -->|是| C[处理订单]
B -->|否| D[拒绝订单]
C & D --> E[结束]

三、时序图（Sequence Diagram）

适用场景

系统交互、接口调用、消息传递、业务时序梳理

基础语法

sequenceDiagram
participant/actor 参与者1
participant/actor 参与者2
消息流向

语法

1. 参与者
   • participant：普通参与者
   • actor：角色/用户
2. 消息类型
   • 同步消息：A ->> B
   • 异步消息：A -->> B
   • 无返回消息：A -) B
3. 激活状态
   • 开启：activate A / A ->> +B
   • 关闭：deactivate A / B -->> -A
4. 循环：loop 循环说明 ... end
5. 并行：par 并行说明 ... end
6. 注释：Note left/right of 参与者: 注释内容
7. 自动编号：autonumber

示例

sequenceDiagram
autonumber
participant 用户
participant 服务器
participant 数据库
用户->>+服务器: 登录请求
服务器->>数据库: 校验账号密码
数据库-->>服务器: 校验结果
服务器-->>-用户: 登录结果

四、甘特图（Gantt Chart）

适用场景

项目规划、进度管理、任务排期、里程碑跟踪

基础语法

gantt
dateFormat 日期格式
axisFormat 坐标轴格式
excludes 排除日期
title 图表标题
section 分组名称
任务定义

语法

1. 日期格式：YYYY-MM-DD
2. 排除日期：weekends、sunday、具体日期
3. 任务状态
   • done：已完成
   • active：进行中
   • crit：关键任务
   • milestone：里程碑
4. 任务时长：d（天）、w（周）、y（年）
5. 任务依赖：after 任务ID

示例

gantt
dateFormat YYYY-MM-DD
axisFormat %Y-%m-%d
excludes weekends
title 项目开发计划
section 研发
需求分析: done, a1, 2025-01-01, 5d
开发编码: active, a2, after a1, 15d
测试验收: a3, after a2, 7d
section 发布
预发布: a4, after a3, 2d
正式上线: milestone, a5, after a4, 0d

五、饼图（Pie Chart）

适用场景

数据占比、资源分布、比例分析

基础语法

pie
title 图表标题
"数据项1": 数值1
"数据项2": 数值2

语法说明

1. 数值支持整数、小数，最多两位小数
2. 无需总和为 100，自动计算比例
3. 可通过 init 配置样式、文字位置

示例

pie
title 月度开销占比
"生活开销": 2000
"娱乐开销": 1000
"其他开销": 800

六、类图（Class Diagram）

适用场景

面向对象设计、系统架构、数据结构建模

基础语法

classDiagram
class 类名 {
权限修饰符 属性类型 属性名
权限修饰符 方法名(参数) 返回值类型
}
类关系

语法

1. 权限修饰符
   • +：公共
   • -：私有
   • #：保护
   • ~：包内可见
   • $：静态
2. 类关系
   • 继承：<|--
   • 实现：--|>
   • 关联：--

示例

classDiagram
class 动物 {
+String name
+void eat()
}
class 鸟类 {
+float wingSpan
+void fly()
}
动物 <|-- 鸟类

七、状态图（State Diagram）

适用场景

系统状态转换、状态机、生命周期管理

基础语法

stateDiagram-v2
[*] --> 初始状态
状态1 --> 状态2: 触发条件
状态2 --> [*]

示例

stateDiagram-v2
[*] --> 空闲
空闲 --> 运行: 启动指令
运行 --> 暂停: 暂停指令
暂停 --> 运行: 恢复指令
运行 --> 结束: 终止指令
结束 --> [*]

八、用户旅行图（User Journey）

适用场景

用户行为路径、体验流程、产品交互设计

基础语法

journey
title 图表标题
section 阶段名称
任务名称: 评分: 参与者

语法说明

• 评分：0-5 分，代表满意度
• 参与者：执行任务的角色，多角色用逗号分隔

示例

journey
title 在线购物流程
section 浏览商品
登录网站: 4: 用户
查看详情: 5: 用户
section 下单支付
提交订单: 5: 用户
支付完成: 3: 用户

九、其他常用图表

1. Git 图

适用场景：代码分支、提交历史、版本管理

gitGraph
commit
commit
branch develop
checkout develop
commit
checkout main
merge develop
commit

2. 时间线图

适用场景：事件历程、里程碑、历史梳理

timeline
title 技术发展时间线
section 2020年
2020: Vue3 发布
section 2021年
2021: React18 发布

3. 桑基图

适用场景：数据流向、资源分配、流量分析

sankey-beta
Source,Target,Value
Home,Product,80
Product,Cart,30
Cart,Pay,25

4. 架构图

适用场景：系统分层、微服务架构、模块依赖

graph LR
subgraph 前端层
Web端
移动端
end
subgraph 服务层
API网关
用户服务
订单服务
end
Web端 --> API网关
移动端 --> API网关
API网关 --> 用户服务
API网关 --> 订单服务

十、通用配置

主题设置

样式自定义

• 节点样式：style 节点ID fill:#颜色,stroke:#颜色
• 子图样式：style 子图ID fill:#颜色

十一、环境配置

1. Typora 配置

1. 文件 → 偏好设置 → Markdown
2. 勾选「Mermaid 图表」
3. 重启编辑器生效

2. Web 项目集成

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>
mermaid.initialize({startOnLoad:true});
</script>
<div class="mermaid">
graph LR
A --> B
</div>

3. 常见问题

1. 图表不渲染：检查语法、重启编辑器、确认插件开启
2. 乱码：避免中英文符号混用，统一使用英文符号
3. 样式异常：升级 Mermaid 版本或编辑器版本

十二、文本对齐相关语法

Mermaid 支持节点文本对齐，以下为 3 种最常用的文本对齐方法，包含左对齐、右对齐、全局统一、单独节点设置。

方法 1：classDef 全局样式（最简洁）

统一给所有节点设置左/右对齐，代码最少

flowchart TD
    %% 1. 定义样式类：左对齐
    classDef left text-align:left;

    %% 流程图节点
    A["Test Image"] --> B["Blur Detection"]
    A --> C["Noise Detection"]
    
    B --> D["Edge Detection"]
    D --> E["Blur decision of detected edges"]
    E --> F["Obtain 2 features<br/>1. The mean of blur<br/>2. The ratio of blur"]
    
    C --> G["Apply averaging Filter"]
    G --> H["Edge detection in the filtered image"]
    H --> I["Noise detection out of edge region"]
    I --> J["Obtain 2 features<br/>1. The mean of noise<br/>2. The ratio of noise"]
    
    F --> K["Combination of features<br/>Proposed metric=1-(w₁*Blur_mean +w₂*Blur_ratio +w₃*Noise_mean +w₄*Noise_ratio)"]
    J --> K

    %% 2. 批量应用样式
    class A,B,C,D,E,F,G,H,I,J,K left;

方法 2：style 单独节点设置（单个节点控制）

只给指定节点设置对齐，不影响其他节点

flowchart TD
    A["Test Image"] --> B["Blur Detection"]
    A --> C["Noise Detection"]
    
    B --> D["Edge Detection"]
    D --> E["Blur decision of detected edges"]
    E --> F["Obtain 2 features<br/>1. The mean of blur<br/>2. The ratio of blur"]
    
    C --> G["Apply averaging Filter"]
    G --> H["Edge detection in the filtered image"]
    H --> I["Noise detection out of edge region"]
    I --> J["Obtain 2 features<br/>1. The mean of noise<br/>2. The ratio of noise"]
    
    F --> K["Combination of features<br/>Proposed metric=1-(w₁*Blur_mean +w₂*Blur_ratio +w₃*Noise_mean +w₄*Noise_ratio)"]
    J --> K

    %% 单独设置每个节点的对齐方式
    style A text-align:left;
    style B text-align:left;
    style C text-align:left;
    style D text-align:left;
    style E text-align:left;
    style F text-align:left;
    style G text-align:left;
    style H text-align:left;
    style I text-align:left;
    style J text-align:left;
    style K text-align:left;

方法3：混合用法（全局+单独节点）

全局默认左对齐，个别节点右对齐，最实用

flowchart TD
    %% 全局默认：左对齐
    classDef allLeft text-align:left;
    classDef nodeRight text-align:right;

    %% 完整流程图
    A["Test Image"] --> D["Edge Detection"]
    A --> G["Apply averaging Filter"]
    D --> E["Blur decision"]
    E --> F["Obtain 2 features<br>1. mean<br>2. ratio"]
    G --> H["Edge detection in filtered image"]
    H --> I["Noise detection"]
    I --> J["Noise features"]
    F --> K["Final proposed metric"]
    J --> K

    %% 全局左对齐 + K节点单独右对齐
    class A,D,E,F,G,H,I,J allLeft;
    class K nodeRight;

文本对齐用法总结

效果	语法	适用场景
节点左对齐	text-align:left;	所有文本靠左（最常用）
节点右对齐	text-align:right;	单独节点靠右
全局统一	classDef 类名 text-align:left;	批量设置所有节点
单个节点	style 节点名 text-align:left;	精准控制单个节点

• 推荐用法：用 classDef定义样式 + class 批量应用，代码最简洁
• 单独控制：用 style 节点 text-align:left/right
• 固定语法：左对齐 left，右对齐 right

其他布局相关语法

• 子图布局：使用 subgraph 标签将节点分组，使结构更清晰
• 连线样式：使用 linkStyle 控制连线粗细、颜色、箭头样式

flowchart TB
    %% 子图布局示例
    subgraph 输入层["🎯 输入层"]
        A["用户输入"]
        B["数据预处理"]
    end
    
    subgraph 处理层["⚙️ 处理层"]
        C["特征提取"]
        D["模型推理"]
        E["结果生成"]
    end
    
    subgraph 输出层["📤 输出层"]
        F["格式化输出"]
        G["响应返回"]
    end
    
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    
    %% 连线样式控制
    linkStyle 0 stroke:#ff6b6b,stroke-width:3px;
    linkStyle 1 stroke:#4ecdc4,stroke-width:2px,stroke-dasharray: 5 5;
    linkStyle 5 stroke:#45b7d1,stroke-width:4px;
    
    %% 样式类定义
    classDef input fill:#e8f4f8,stroke:#333;
    classDef process fill:#fff4e6,stroke:#333;
    classDef output fill:#f0f8e8,stroke:#333;
    
    class A,B input;
    class C,D,E process;
    class F,G output;

• 高级布局：支持水平/垂直混合布局、手动指定层级 rank、固定节点位置（实验性）

其他流程图绘制工具

文本代码式（与 Mermaid 同类，通过编写代码生成图表）

• PlantUML：最流行的文本式绘图工具，支持多种图表类型，兼容性强
• Graphviz：底层绘图引擎，语法简洁，常用于学术、科研场景
• D2：新式极简语法，上手难度低，生成图表美观
• TikZ：LaTeX 环境下的绘图工具，适合论文、学术文档中插入流程图
• Markmap：基于 Markdown 语法的思维导图工具，可间接用于简单流程梳理

---

电与磁图示例

Electricity and Magnetism（电与磁）

第一层：按学科领域划分

1. Electromagnetism Fundamentals（电磁学基础）
2. Circuit Theory（电路理论）
3. Circuit Components（电路元件）
4. Electronics（电子学）
5. Applications（应用领域）
6. Bioelectricity（生物电学）

第二层：细分归属

1. Electromagnetism Fundamentals（电磁学基础）

• Electrostatics（静电学）
  • Electric Charge（电荷）
  • Coulomb’s Law（库仑定律）
  • Gauss’s Law（高斯定律）
• Magnetostatics（静磁学）
  • Magnetic Field（磁场）
  • Ampere’s Law（安培定律）
  • Biot-Savart Law（毕奥-萨伐尔定律）
• Electromagnetic Induction（电磁感应）
  • Faraday’s Law（法拉第定律）
  • Lorentz Force Law（洛伦兹力定律）
• Electromagnetic Field Theory（电磁场理论）
  • Maxwell’s Equations（麦克斯韦方程组）
  • EM Waves（电磁波）
• Basic Circuit-Related Quantities
  • EMF（电动势）
  • Voltage（电压）
  • Electric Current（电流）

2. Circuit Theory（电路理论）

• Circuit Laws（电路定律）
  • Kirchhoff’s Voltage Law（KVL 电压定律）
  • Kirchhoff’s Current Law（KCL 电流定律）
  • Ohm’s Law（欧姆定律）
• Circuit Types
  • DC Circuits（直流电路）
  • AC Circuits（交流电路）
• Circuit Energy & Power
  • Electric Power（电功率）
• Practical Wiring
  • Household Wiring（家庭布线）

3. Circuit Components（电路元件）

• Passive Components
  • Resistor（电阻）
  • Capacitor（电容）
  • Inductor（电感）

4. Electronics（电子学）

（可继续扩展：二极管、三极管、放大电路、数字电路等）

5. Applications（应用）

6. Bioelectricity（生物电学）

基础结构图

带分类颜色样式

带节点形状

嵌套子图结构

---

Mermaid 常用语法速查

方向

• TD / TB：从上到下
• BT：从下到上
• LR：从左到右
• RL：从右到左

节点形状

• id[文本] 矩形
• id(文本) 圆角矩形
• id((文本)) 圆形
• id{文本} 菱形
• id>文本] 不对称矩形
• id[文本:::cyl] 圆柱（数据库）
• id[文本:::diam] 决策菱形

连线

• --> 实线箭头
• --- 实线无箭头
• -.-> 虚线箭头
• ==> 粗线箭头
• --文本--> 带文字连线

着色样式

graph TD
    A[开始] --> B[执行]
    B --> C[结束]

    %% 定义样式
    classDef highlight fill:#ffeb3b,stroke:#f57f17,stroke-width:3px
    classDef normal fill:#e3f2fd,stroke:#1976d2,stroke-width:2px

    %% 应用样式
    class A,C highlight
    class B normal

---

reference

• mermaid大全（语法、流程图、时序图、甘特图、饼图、用户旅行图、类图）_mermaid 时序图-CSDN博客
  https://blog.csdn.net/weixin_44878336/article/details/145095671

• 【Mermaid】5 分钟掌握 Mermaid：从流程图到时序图，一篇文章搞定技术文档可视化全场景_mermaid sequencediagram-CSDN博客
  https://blog.csdn.net/qq_24052051/article/details/149105528

• Mermaid使用教程（绘制各种图）_mermaid语法-CSDN博客
  https://blog.csdn.net/m0_54218263/article/details/135705778

• Mermaid 完整教程 | 在线Mermaid图表编辑器器 - 流程图、序列图和甘特图编辑器
  https://tooltool.net/zh/mermaid/tutorial

• Mermaid 在线编辑器
  https://mermaid-live.nodejs.cn/edit