Luo

Mermaid 入门指南：快速看懂基本语法并修改代码

从流程图、时序图、类图、状态图和实体关系图入手，掌握 Mermaid 的基本语法、修改方法与常见报错排查。

MermaidMarkdown技术教程
阅读 -- 次 参与评论

Mermaid 入门指南：快速看懂基本语法并修改代码

Mermaid 使用文本描述流程图、时序图、类图、状态图和实体关系图。阅读代码时，重点关注：

  1. 第一行：图表类型和方向。
  2. 节点 ID：例如 A、B、User。
  3. 节点标签：例如 A[开始] 中的“开始”。
  4. 连接关系：例如 A --> B。
  5. 代码块结构：例如 subgraph、alt、loop 对应的 end。

本文中每个示例都分成两部分：

  • “源码”：使用 text 代码块，方便查看和复制语法。
  • “预览”：使用 mermaid 代码块，查看渲染效果。

1. Mermaid 代码的基本结构

源码

flowchart LR
    A[开始] --> B[处理任务]

预览

flowchart LR
    A[开始] --> B[处理任务]

这段代码可以拆成四部分：

代码含义
flowchart图表类型，这里是流程图
LR从左到右排列
A[开始]ID 是 A，显示文字是“开始”
-->带箭头的连接线

常见图表类型包括：

开头适合描述
flowchart流程、判断、系统结构
sequenceDiagram用户、服务之间的调用顺序
classDiagram类、属性、方法和类之间的关系
stateDiagram-v2状态变化
erDiagram数据库实体关系
mindmap思维导图

2. 流程图

流程图由节点和连接线组成，官方文档支持多种方向、节点形状和连接方式。Mermaid Flowchart 官方文档

2.1 设置方向

源码

flowchart TD
    A[开始] --> B[结束]

预览

flowchart TD
    A[开始] --> B[结束]

常见方向：

写法含义
TD 或 TB从上到下
LR从左到右
RL从右到左
BT从下到上

修改方向时，只需要修改第一行：

源码

flowchart LR
    A[开始] --> B[结束]

预览

flowchart LR
    A[开始] --> B[结束]

2.2 常见节点形状

源码

flowchart LR
    A[处理数据]
    B(开始)
    C{是否成功?}
    D((连接点))
    E[(数据库)]
    F[/用户输入/]

预览

flowchart LR
    A[处理数据]
    B(开始)
    C{是否成功?}
    D((连接点))
    E[(数据库)]
    F[/用户输入/]

常用写法：

写法图形常见用途
A[文本]矩形普通步骤
A(文本)圆角矩形开始、结束
A{文本}菱形条件判断
A((文本))圆形起点、连接点
A[(文本)]圆柱数据库
A[/文本/]平行四边形输入、输出

2.3 连接线和分支

源码

flowchart TD
    Start([开始]) --> Submit[提交表单]
    Submit --> Check{校验通过?}
    Check -->|是| Save[(保存数据)]
    Check -->|否| Error[显示错误]

预览

flowchart TD
    Start([开始]) --> Submit[提交表单]
    Submit --> Check{校验通过?}
    Check -->|是| Save[(保存数据)]
    Check -->|否| Error[显示错误]

常见连接线：

写法含义
A --> B带箭头的实线
A --- B无箭头的实线
A -.-> B虚线箭头
A ==> B粗线箭头
`A —>通过

2.4 子图

subgraph 可以把多个节点分成一个区域。

源码

flowchart LR
    subgraph 前端
        Page[页面]
        Form[表单]
        Page --> Form
    end

    subgraph 后端
        API[接口]
        DB[(数据库)]
        API --> DB
    end

    Form --> API

预览

flowchart LR
    subgraph 前端
        Page[页面]
        Form[表单]
        Page --> Form
    end

    subgraph 后端
        API[接口]
        DB[(数据库)]
        API --> DB
    end

    Form --> API

subgraph 必须使用 end 结束。

3. 时序图

时序图用于表示多个参与者之间按时间发生的交互。Mermaid Sequence Diagram 官方文档

源码

sequenceDiagram
    participant User as 用户
    participant App as 应用
    participant API as 接口

    User->>App: 点击登录
    App->>API: 发送账号密码
    API-->>App: 返回登录结果
    App-->>User: 显示首页

预览

sequenceDiagram
    participant User as 用户
    participant App as 应用
    participant API as 接口

    User->>App: 点击登录
    App->>API: 发送账号密码
    API-->>App: 返回登录结果
    App-->>User: 显示首页

阅读时重点看：

  • participant：参与者。
  • A->>B：A 调用 B。
  • B-->>A：B 返回给 A。
  • 冒号后面的文字：消息内容。
  • 代码从上到下：调用顺序。

3.1 条件分支和循环

源码

sequenceDiagram
    participant User as 用户
    participant API as 接口

    User->>API: 提交登录请求

    alt 登录成功
        API-->>User: 返回令牌
    else 登录失败
        API-->>User: 返回错误信息
    end

    loop 每隔一分钟
        User->>API: 查询登录状态
    end

预览

sequenceDiagram
    participant User as 用户
    participant API as 接口

    User->>API: 提交登录请求

    alt 登录成功
        API-->>User: 返回令牌
    else 登录失败
        API-->>User: 返回错误信息
    end

    loop 每隔一分钟
        User->>API: 查询登录状态
    end

alt、else、end 表示条件块；loop、end 表示循环块。

4. 类图

类图用于表示类、属性、方法和类之间的关系。Mermaid Class Diagram 官方文档

源码

classDiagram
    class User {
        +String name
        +login()
    }

    class Order {
        +int id
        +submit()
    }

    User "1" --> "*" Order : 创建

预览

classDiagram
    class User {
        +String name
        +login()
    }

    class Order {
        +int id
        +submit()
    }

    User "1" --> "*" Order : 创建

类成员的可见性：

符号含义
+public，公开
-private，私有
#protected，受保护
~package 或内部可见

4.1 类之间的关系

源码

classDiagram
    Animal <|-- Dog
    Car ..> Engine : 使用

预览

classDiagram
    Animal <|-- Dog
    Car ..> Engine : 使用

常见关系：

写法含义
`<—`
*--组合
o--聚合
-->关联
..>依赖
`..>`

5. 状态图

状态图关注当前状态以及状态之间的转换。Mermaid State Diagram 官方文档

源码

stateDiagram-v2
    [*] --> LoggedOut

    LoggedOut: 未登录
    LoggingIn: 登录中
    LoggedIn: 已登录

    LoggedOut --> LoggingIn: 点击登录
    LoggingIn --> LoggedIn: 验证成功
    LoggingIn --> LoggedOut: 验证失败

    LoggedIn --> [*]: 退出登录

预览

stateDiagram-v2
    [*] --> LoggedOut

    LoggedOut: 未登录
    LoggingIn: 登录中
    LoggedIn: 已登录

    LoggedOut --> LoggingIn: 点击登录
    LoggingIn --> LoggedIn: 验证成功
    LoggingIn --> LoggedOut: 验证失败

    LoggedIn --> [*]: 退出登录

状态转换可以读成：

当前状态 --触发事件--> 下一个状态

例如：

未登录 --点击登录--> 登录中
登录中 --验证成功--> 已登录

6. 实体关系图

实体关系图常用于数据库设计。Mermaid ER Diagram 官方文档

源码

erDiagram
    CUSTOMER ||--o{ ORDER : places

    CUSTOMER {
        string id
        string name
    }

    ORDER {
        string id
        string status
    }

预览

erDiagram
    CUSTOMER ||--o{ ORDER : places

    CUSTOMER {
        string id
        string name
    }

    ORDER {
        string id
        string status
    }

常见关系符号：

符号含义
`
`o`
o{零个或多个
`{`

例如：

源码

erDiagram
    ORDER ||--|{ ORDER_ITEM : contains

预览

erDiagram
    ORDER ||--|{ ORDER_ITEM : contains

7. 如何修改 Mermaid 代码

假设原代码如下。

原始源码

flowchart LR
    A[提交] --> B{校验}
    B -->|通过| C[保存]
    B -->|失败| D[提示错误]

原始预览

flowchart LR
    A[提交] --> B{校验}
    B -->|通过| C[保存]
    B -->|失败| D[提示错误]

现在要实现三个修改：

  • 改成从上到下排列。
  • 节点文字更清楚。
  • 保存后增加“发送通知”。

修改后的源码

flowchart TD
    A[提交订单] --> B{校验通过?}
    B -->|通过| C[保存订单]
    C --> E[发送通知]
    B -->|失败| D[显示错误]

修改后的预览

flowchart TD
    A[提交订单] --> B{校验通过?}
    B -->|通过| C[保存订单]
    C --> E[发送通知]
    B -->|失败| D[显示错误]

修改时可以按照这个顺序：

  1. 看第一行，确认图表类型和方向。
  2. 保留已有 ID，例如 A、B、C。
  3. 修改节点显示文字，例如 A[提交] 改成 A[提交订单]。
  4. 修改连接关系，例如增加 C --> E。
  5. 检查 subgraph、alt、loop 等结构的 end 是否成对。
  6. 放入编辑器预览。

节点 ID 是连接关系的依据。只改括号里的文字，通常不会影响连线；如果把 B 改成 Check，还需要同步修改所有引用 B 的连接线。

8. 常见报错原因

8.1 标签中有特殊字符

源码

flowchart LR
    A["请求 /api/order?id=1"] --> B["返回 JSON"]

预览

flowchart LR
    A["请求 /api/order?id=1"] --> B["返回 JSON"]

8.2 end 被当成特殊关键字

流程图中的节点文字如果使用全小写 end，可能导致解析失败。可以改成大写或使用引号。

源码

flowchart LR
    A[End] --> B[完成]

预览

flowchart LR
    A[End] --> B[完成]

也可以使用引号：

源码

flowchart LR
    A["end"] --> B[完成]

预览

flowchart LR
    A["end"] --> B[完成]

8.3 忘记写结束标记

源码

sequenceDiagram
    participant A as 用户
    participant B as 服务

    alt 请求成功
        A->>B: 请求
    else 请求失败
        B-->>A: 错误
    end

预览

sequenceDiagram
    participant A as 用户
    participant B as 服务

    alt 请求成功
        A->>B: 请求
    else 请求失败
        B-->>A: 错误
    end

8.4 编辑器版本不同

Mermaid 的部分新语法依赖较新的版本。如果同一段代码在一个编辑器能显示，在另一个编辑器报错，可以先检查编辑器内置的 Mermaid 版本。

最简单的验证方式是使用官方 Mermaid Live Editor，先粘贴最小代码。

源码

flowchart LR
    A[开始] --> B[结束]

预览

flowchart LR
    A[开始] --> B[结束]

确认最小代码可以渲染后，再逐行加入复杂逻辑。

9. Mermaid 语法速查表

需求写法
流程图flowchart LR
从上到下flowchart TD
矩形节点A[文本]
判断节点A{条件}
数据库节点A[(数据库)]
节点连线A --> B
带文字连线`A —>
创建分组subgraph 名称
结束分组end
时序图sequenceDiagram
发起消息A->>B: 请求
返回消息B-->>A: 返回
条件分支alt 条件
循环loop 条件
类图classDiagram
定义类class User
继承`Animal <
状态图stateDiagram-v2
状态转换A --> B
开始状态[*] --> A
结束状态A --> [*]
实体关系图erDiagram

掌握“第一行看类型、括号看节点、箭头看关系、冒号看说明、end 看结构”，就能读懂和修改大部分常见 Mermaid 代码。

评论

使用 GitHub 登录参与讨论。