NW' Blog
2026年7月10日 · 内容页面

Mermaid 语法大全

Mermaid 是一个基于 JavaScript 的图表绘制工具,通过解析类 Markdown 的文本语法,在浏览器中实时渲染为矢量图表。本文档汇总了 Mermaid 所有常用图表类型的语法。


一、基础概念

1.1 基本结构

所有 Mermaid 图表都需要包裹在代码块中,语言标识为 mermaid

Mermaid
<div class="mermaid-wrapper"><div class="mermaid">
gitGraph LR:
   checkout main
   commit id: "Downtown" tag: "Line 1"
   commit id: "Central Park"
   branch "Line 2 (Blue)"
   commit id: "East Station"
   commit id: "Science Museum"
   checkout main
   commit id: "City Hall (Transfer)" tag: "🔀 Line 1 & 2"
   merge "Line 2 (Blue)"
   commit id: "Financial District"
   branch "Line 3 (Green)"
   commit id: "West Village"
   commit id: "Airport Terminal"
   checkout main
   commit id: "Sports Arena"
   merge "Line 3 (Green)"
   commit id: "Northern Gateway"
   branch "Line 4 (Orange)"
   commit id: "University"
   checkout main
   commit id: "Central Station" tag: "Terminal"
   merge "Line 4 (Orange)"
</div></div>
gitGraph LR: checkout main commit id: "Downtown" tag: "Line 1" commit id: "Central Park" branch "Line 2 (Blue)" commit id: "East Station" commit id: "Science Museum" checkout main commit id: "City Hall (Transfer)" tag: "🔀 Line 1 & 2" merge "Line 2 (Blue)" commit id: "Financial District" branch "Line 3 (Green)" commit id: "West Village" commit id: "Airport Terminal" checkout main commit id: "Sports Arena" merge "Line 3 (Green)" commit id: "Northern Gateway" branch "Line 4 (Orange)" commit id: "University" checkout main commit id: "Central Station" tag: "Terminal" merge "Line 4 (Orange)"

需要在文件最后添加 Mermaid 组件的相关代码:

Mermaid
<style is:global>
  @import url('../styles/mermaid-toolbar.css');
</style>

<script>
  import '../scripts/mermaid-toolbar.js';
</script>

<script is:inline>
  document.addEventListener('DOMContentLoaded', function() {
    var script = document.createElement('script');
    script.src = 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js';
    script.onload = function() {
      mermaid.initialize({
        startOnLoad: false,
        theme: 'dark',
        themeVariables: {
          background: '#1a1a2e',
          primaryColor: '#4a90d9',
          secondaryColor: '#2d2d44',
          tertiaryColor: '#1a1a2e',
          primaryBorderColor: '#555',
          secondaryBorderColor: '#444',
          lineColor: '#888',
          textColor: '#f6f2e9',
          mainBkg: '#2d2d44',
          nodeBorder: '#555',
          clusterBkg: '#1a1a2e',
          clusterBorder: '#333',
          titleColor: '#f6f2e9',
          edgeLabelBackground: '#2d2d44',
          nodeTextColor: '#f6f2e9',
        }
      });
      mermaid.run({ querySelector: '.mermaid' }).then(function() {
        if (window.MermaidToolbar) {
          window.MermaidToolbar.initToolbars();
        }
      });
    };
    document.head.appendChild(script);
  });
</script>

1.2 注释

使用 %% 添加注释,注释内容不会被渲染:

Mermaid
graph TD
            A[开始] --> B{判断}  %% 这是一条注释
            B -->|是| C[执行]

二、流程图(Flowchart)

流程图是最常用的图表类型,用于描述流程、算法和决策逻辑。

2.1 方向设置

方向 语法 说明
从上到下 TDTB 最常用
从左到右 LR 适合步骤较多的流程
从右到左 RL 较少用
从下到上 BT 较少用

2.2 节点形状

形状 语法 说明
矩形 A[文本] 普通步骤
圆角矩形 A(文本) 开始/结束
圆形 A((文本)) 开始/结束
菱形 A{文本} 判断条件
六边形 A{{文本}} 准备/预备
平行四边形 A[/文本/] 输入/输出
圆柱形 A[(文本)] 数据库

2.3 连线类型

连线 语法 说明
带箭头 --> 实线箭头
带文字 `--> 文字
无箭头 --- 实线无箭头
粗箭头 ==> 粗线箭头
虚线箭头 -.-> 点线箭头
带文字虚线 `-.-> 文字

2.4 基础示例

Mermaid
flowchart TD
    A[开始] --> B{是否登录}
    B -->|是| C[进入主页]
    B -->|否| D[跳转登录页]
    C --> E[结束]
    D --> E
flowchart TD A[开始] --> B{是否登录} B -->|是| C[进入主页] B -->|否| D[跳转登录页] C --> E[结束] D --> E

2.5 子图(Subgraph)

使用 subgraph 对节点进行逻辑分组:

Mermaid
flowchart TD
    subgraph 用户模块
        A[用户注册] --> B[用户登录]
    end
    subgraph 业务模块
        C[浏览商品] --> D[下单支付]
    end
    B --> C
flowchart TD subgraph 用户模块 A[用户注册] --> B[用户登录] end subgraph 业务模块 C[浏览商品] --> D[下单支付] end B --> C

2.6 自定义样式

使用 classDef 定义样式类,再用 class 应用:

Mermaid
flowchart LR
    A[开始] --> B[处理]
    classDef red fill:#f99,stroke:#333,stroke-width:2px
    class A red 
flowchart LR A[开始] --> B[处理] classDef red fill:#f99,stroke:#333,stroke-width:2px class A red

三、时序图(Sequence Diagram)

时序图用于展示对象间的消息交互顺序。

3.1 基本语法

Mermaid
sequenceDiagram
    participant 用户
    participant 服务器
    用户->>服务器: 发送请求
    服务器-->>用户: 返回响应
sequenceDiagram participant 用户 participant 服务器 用户->>服务器: 发送请求 服务器-->>用户: 返回响应

3.2 参与者定义

使用 participant 定义参与者,可用 as 取别名:

Mermaid
sequenceDiagram
    participant U as 用户
    participant S as 服务端
    U->>S: 请求数据
sequenceDiagram participant U as 用户 participant S as 服务端 U->>S: 请求数据

3.3 消息类型

类型 语法 说明
实线箭头 ->> 同步消息
虚线箭头 -->> 异步响应
实线无箭头 -> 简单消息
虚线无箭头 --> 简单响应
带叉箭头 -x 异步消息
带括号箭头 -) 异步消息

3.4 激活框

使用 +- 标记激活和停用:

Mermaid
sequenceDiagram
    A->>+B: 请求
    B-->>-A: 响应
sequenceDiagram A->>+B: 请求 B-->>-A: 响应

3.5 注释

Mermaid
sequenceDiagram
    participant A
    participant B
    Note right of A: 这是注释
    Note left of B: 左侧注释
    Note over A,B: 跨参与者注释
sequenceDiagram participant A participant B Note right of A: 这是注释 Note left of B: 左侧注释 Note over A,B: 跨参与者注释

3.6 高级结构

循环(loop)

Mermaid
sequenceDiagram
    loop 每天执行
        A->>B: 检查状态
    end
sequenceDiagram loop 每天执行 A->>B: 检查状态 end

条件分支(alt/else)

Mermaid
sequenceDiagram
    alt 成功
        A->>B: 继续处理
    else 失败
        A->>B: 重试
    end
sequenceDiagram alt 成功 A->>B: 继续处理 else 失败 A->>B: 重试 end

并行(par)

Mermaid
sequenceDiagram
    par 并行执行
        A->>B: 任务1
    and
        A->>C: 任务2
    end
sequenceDiagram par 并行执行 A->>B: 任务1 and A->>C: 任务2 end

四、类图(Class Diagram)

类图用于描述系统的静态结构,包括类、属性、方法及其关系。

4.1 基本语法

Mermaid
classDiagram
    class Animal {
        +String name
        -int age
        +void eat()
        -void sleep()
    }
classDiagram class Animal { +String name -int age +void eat() -void sleep() }

4.2 可见性标识

符号 含义
+ 公有(public)
- 私有(private)
# 保护(protected)
~ 包内(package)

4.3 关系类型

关系 语法 说明
继承 `< --`
实现 ..|> 接口实现
组合 *-- 强拥有关系
聚合 o-- 弱拥有关系
关联 --> 普通关联

4.4 完整示例

Mermaid
classDiagram
    Animal <|-- Dog
    Animal <|-- Cat
    Animal : +String name
    Animal : +void move()
    class Dog { 
        +String breed
        +void bark()
    }
classDiagram Animal <|-- Dog Animal <|-- Cat Animal : +String name Animal : +void move() class Dog { +String breed +void bark() }

五、状态图(State Diagram)

状态图用于描述状态机、生命周期和状态转换。

5.1 基本语法

Mermaid
stateDiagram-v2
    [*] --> 待审核
    待审核 --> 已通过
    待审核 --> 已拒绝
    已通过 --> [*]
    已拒绝 --> [*]
stateDiagram-v2 [*] --> 待审核 待审核 --> 已通过 待审核 --> 已拒绝 已通过 --> [*] 已拒绝 --> [*]

5.2 带描述的状态

Mermaid
stateDiagram-v2
    State1: 第一个状态
    State2: 第二个状态
    [*] --> State1
    State1 --> State2
stateDiagram-v2 State1: 第一个状态 State2: 第二个状态 [*] --> State1 State1 --> State2

5.3 复合状态

Mermaid
stateDiagram-v2
    [*] --> 运行中
    state 运行中 { 
        [*] --> 就绪
        就绪 --> 执行中
        执行中 --> 就绪
    } 
    运行中 --> [*]
stateDiagram-v2 [*] --> 运行中 state 运行中 { [*] --> 就绪 就绪 --> 执行中 执行中 --> 就绪 } 运行中 --> [*]

5.4 分支(fork/join)

Mermaid
stateDiagram-v2
    state fork <<fork>>
    [*] --> fork
    fork --> 状态A
    fork --> 状态B
stateDiagram-v2 state fork <<fork>> [*] --> fork fork --> 状态A fork --> 状态B

六、甘特图(Gantt Chart)

甘特图用于项目进度管理和时间线追踪。

6.1 基本语法

Mermaid
gantt
    title 项目开发计划
    dateFormat YYYY-MM-DD
    section 需求阶段
        需求分析    :done, a1, 2024-01-01, 7d
        需求评审    :active, a2, after a1, 3d
    section 开发阶段
        前端开发    :a3, after a2, 14d
        后端开发    :a4, after a2, 21d
    section 测试阶段
        集成测试    :a5, after a3, 7d
gantt title 项目开发计划 dateFormat YYYY-MM-DD section 需求阶段 需求分析 :done, a1, 2024-01-01, 7d 需求评审 :active, a2, after a1, 3d section 开发阶段 前端开发 :a3, after a2, 14d 后端开发 :a4, after a2, 21d section 测试阶段 集成测试 :a5, after a3, 7d

6.2 任务状态

状态 说明
done 已完成
active 进行中
crit 关键路径
milestone 里程碑

七、饼图(Pie Chart)

饼图用于展示比例和分布。

Mermaid
pie title 编程语言使用比例
    "JavaScript" : 45
    "Python" : 30
    "Java" : 15
    "Go" : 10
pie title 编程语言使用比例 "JavaScript" : 45 "Python" : 30 "Java" : 15 "Go" : 10

使用 showData 显示具体数值:

Mermaid
pie showData
    title 市场份额
    "产品A" : 35.5
    "产品B" : 28.3
    "产品C" : 20.2
    "其他" : 16.0
pie showData title 市场份额 "产品A" : 35.5 "产品B" : 28.3 "产品C" : 20.2 "其他" : 16.0

八、实体关系图(ER Diagram)

ER 图用于数据库关系建模。

8.1 基数表示

语法 含义
`
` o`
}o 零或多个
`} `

8.2 示例

Mermaid
erDiagram
    CUSTOMER ||--o{  ORDER : 下单
    ORDER ||--|{  LINE_ITEM : 包含
    PRODUCT ||--o{  LINE_ITEM : 属于
    CUSTOMER { 
        int id PK
        string name
        string email
    } 
    ORDER { 
        int id PK
        int customer_id FK
        date created_at
    } 
erDiagram CUSTOMER ||--o{ ORDER : 下单 ORDER ||--|{ LINE_ITEM : 包含 PRODUCT ||--o{ LINE_ITEM : 属于 CUSTOMER { int id PK string name string email } ORDER { int id PK int customer_id FK date created_at }

九、用户旅程图(User Journey)

用户旅程图描述用户完成任务的具体步骤。

Mermaid
journey
    title 购物体验
    section 浏览商品
        查看商品列表: 5: 用户
        搜索商品: 4: 用户
    section 下单支付
        加入购物车: 4: 用户
        填写地址: 3: 用户
        支付成功: 5: 用户, 系统
journey title 购物体验 section 浏览商品 查看商品列表: 5: 用户 搜索商品: 4: 用户 section 下单支付 加入购物车: 4: 用户 填写地址: 3: 用户 支付成功: 5: 用户, 系统

评分范围为 1-5,表示满意度。

十、Git 分支图(GitGraph)

Git 分支图用于可视化版本控制分支和提交历史。

10.1 基本语法

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

10.2 带标签的提交

Mermaid
gitGraph
    commit id: "初始化"
    commit id: "添加功能"
    branch feature
    checkout feature
    commit id: "开发新功能"
    checkout main
    merge feature id: "合并功能"
gitGraph commit id: "初始化" commit id: "添加功能" branch feature checkout feature commit id: "开发新功能" checkout main merge feature id: "合并功能"

10.3 分支操作

Mermaid
gitGraph
    commit
    branch dev
    checkout dev
    commit
    branch feature
    checkout feature
    commit
    checkout dev
    merge feature
    checkout main
    merge dev tag: "v1.0.0"
gitGraph commit branch dev checkout dev commit branch feature checkout feature commit checkout dev merge feature checkout main merge dev tag: "v1.0.0"

十一、看板图(Kanban)

看板图用于任务板和流程阶段管理。

Mermaid
kanban
    待办
        需求分析
        设计评审
    进行中
        前端开发
    已完成
        项目初始化
kanban 待办 需求分析 设计评审 进行中 前端开发 已完成 项目初始化

十二、象限图(Quadrant Chart)

象限图用于优先级排序和趋势分析。

Mermaid
quadrantChart
    x-axis 低优先级 --> 高优先级
    y-axis 低影响 --> 高影响
    紧急任务: [0.8, 0.9]
    日常事务: [0.3, 0.4]
    战略规划: [0.6, 0.7]
    琐碎杂事: [0.2, 0.2]
quadrantChart x-axis 低优先级 --> 高优先级 y-axis 低影响 --> 高影响 紧急任务: [0.8, 0.9] 日常事务: [0.3, 0.4] 战略规划: [0.6, 0.7] 琐碎杂事: [0.2, 0.2]

十三、架构图(Architecture Diagram)

用于云基础设施和服务架构可视化。

Mermaid
architecture-beta
    service api(server)[APIService]
    service db(database)[Database]
    service cache(database)[Cache]
    api:R --< L:db
    api:R --< L:cache
architecture-beta service api(server)[APIService] service db(database)[Database] service cache(database)[Cache] api:R --> L:db api:R --> L:cache

十四、区块图(Block Diagram)

用于模块依赖和网络可视化。

Mermaid
block-beta
    columns 3
    a["模块A"] b["模块B"] c["模块C"]
    a --< b
    b --< c
block-beta columns 3 a["模块A"] b["模块B"] c["模块C"] a --> b b --> c

十五、C4 模型图(C4 Diagram)

用于系统架构的 C4 模型可视化。

Mermaid
C4Context
    title 系统上下文图
    Person(user, "用户", "系统使用者")
    System(app, "应用系统", "核心业务系统")
    Rel(user, app, "使用", "HTTPS")
C4Context title 系统上下文图 Person(user, "用户", "系统使用者") System(app, "应用系统", "核心业务系统") Rel(user, app, "使用", "HTTPS")

十六、通用技巧

16.1 换行

使用 <br> 实现节点内换行:

Mermaid
flowchart LR
    A[第一行
第二行
第三行] --> B[结果]

16.2 特殊字符

如果节点文本包含特殊字符或关键字(如 end),使用引号包裹:

Mermaid
flowchart TD
    A["包含特殊字符的文本"]
    B["end 关键字"]
flowchart TD A["包含特殊字符的文本"] B["end 关键字"]

16.3 在线调试

推荐使用 Mermaid Live Editor 进行在线调试和预览。

附录:图表类型速查表

图表类型 关键字 用途
流程图 flowchart / graph 流程逻辑、决策树
时序图 sequenceDiagram 消息交互顺序
类图 classDiagram 面向对象结构
状态图 stateDiagram-v2 状态机、生命周期
甘特图 gantt 项目进度管理
饼图 pie 比例分布
ER 图 erDiagram 数据库关系
用户旅程图 journey 用户体验流程
Git 分支图 gitGraph 版本控制可视化
看板图 kanban 任务管理
象限图 quadrantChart 优先级分析
架构图 architecture-beta 云基础设施
区块图 block-beta 模块依赖
C4 模型图 C4Context 系统架构
评论区 留下您的想法
教程