mermaid-syntax

Mermaid 图表语法指南

生成无错误 Mermaid 图表的全面语法参考。避免常见错误，并支持 Mermaid v11 功能，包括流程图、时序图、类图、状态图、ER 图、甘特图等。

测试图表： https://mermaid.live/

优先使用 flowchart，而非 graph： 两者都可用，但 flowchart 是较新的语法，功能支持更完善。

关键规则（可避免 90% 的错误）

1. 特殊字符转义

文本包含特殊字符时，务必用双引号括起来：

flowchart LR
    A["Text with (parentheses)"]
    B["Text with / or \ slashes"]
    C["Colon: in text"]

需要加引号的字符： ( ) [ ] { } / \ : ; # @ ! ? < > " '

2. 保留字（不只是 “end”！）

多个保留字会导致图表无法正常显示。使用带安全 ID 的引号标签：

flowchart LR
    node1["end"]           %% Safe: quoted with different ID
    node2["default"]       %% Safe: "default" is also reserved
    node3["End"]           %% Safe: capitalized

所有保留字（使用带引号的标签）：

• end、default
• style、linkStyle、classDef、class
• call、href、click、interpolate

模式： 使用 safeId["保留字文本"]，而非 reserved[text]

3. 节点 ID 的起始字符

以 o 或 x 开头的节点会生成意料之外的边类型：

flowchart LR
    orderNode[Order]    %% Good: full word
    oNode[O-Node]       %% Bad: might create circle edge

解决方案： 使用描述性 ID，避免以单个字母 o 或 x 开头。

4. 分号的 HTML 实体代码

在时序图中，分号用于定义换行。要表示字面分号，请使用 #59;：

sequenceDiagram
    A->>B: Value#59; Key#59; Data

5. 注释必须使用 %%

单个 % 会导致图表无法正常显示。务必使用 %%：

flowchart LR
    %% This is a valid comment
    A --> B

6. 带 HTML 标签的子图

子图标题包含 <br/> 时，请用引号括起来：

flowchart TB
    subgraph "Title with<br/>line break"
        A --> B
    end

7. 样式属性转义

使用反斜杠转义 stroke-dasharray 中的逗号：

flowchart LR
    A --> B
    linkStyle 0 stroke-dasharray: 5\,5

8. Frontmatter 必须位于首行

Frontmatter 的 --- 必须是第 1 行中唯一的内容：

---
config:
  theme: forest
---
flowchart LR
    A --> B

错误示例： --- 前的任何空格或内容都会导致图表无法正常显示。

9. 思维导图中的 < 字符问题

在思维导图中，< 会渲染为 <。请改用文字：

mindmap
    root((Comparison))
        Less than 10    %% Instead of "< 10"
        Greater than 5  %% Instead of "> 5"

10. 类图中的冒号限制

类成员类型中的冒号较难处理。请使用返回类型语法：

classDiagram
    class MyClass {
        +getData() Map~String, Object~
    }

注意： 含冒号的复杂泛型类型可能无法正确渲染。

11. 嵌套子图链接问题

同时链接到父子图和嵌套子图会导致语法错误：

flowchart LR
    %% BAD: linking to both system AND sub-system breaks
    %% A --> system
    %% B --> sub-system

    %% GOOD: link to nodes inside, not subgraph itself
    A --> service1
    B --> service2

    subgraph system
        subgraph sub-system
            service1
            service2
        end
    end

解决方法： 链接到子图内的节点，而不要直接链接到子图 ID。

12. 子图方向继承

如果子图中的节点链接到外部节点，方向设置会被忽略（继承父图方向）：

flowchart LR
    A --> B
    subgraph sub [My Subgraph]
        direction TB  %% Ignored if C links outside!
        C --> D
    end
    B --> C  %% This external link forces LR direction

规则： 只有所有节点都留在子图内部时，子图方向设置才会生效。

13. v11 无箭头边的问题（v11.0-11.4）

在 Mermaid v11.0 至 v11.4.x 中，---（无箭头的线）语法存在问题，会显示箭头：

flowchart LR
    %% BROKEN in v11.0-11.4: shows arrow instead of line
    A --- B

    %% Workaround: use explicit arrow and style
    C --> D
    linkStyle 0 stroke:#333,stroke-width:2px

修复方法： 升级到 Mermaid v11.5.0 或更高版本。

14. v11 默认使用 Markdown 的破坏性变更

在 v11 中，所有节点标签默认都会渲染为 Markdown（这是相较于 v10 的破坏性变更）：

flowchart LR
    %% v10: plain text, v11: renders as Markdown
    A[**bold** and _italic_]

    %% Problem: underscores in text become italic
    B["file_name_here"]  %% Use quotes to prevent issues

注意： 仅支持粗体（**）和斜体（_ 或 *）。反引号括起的行内代码可能无法正常使用。

15. 配置限制（安全设置）

maxTextSize（默认值：50,000 个字符）和 maxEdges（默认值：500）是安全设置，无法通过 frontmatter 设置：

---
config:
  maxTextSize: 100000  %% IGNORED! Secure setting
---
flowchart LR
    A --> B

解决方法： 必须通过 JavaScript 中的 mermaid.initialize() 设置，而不能在图表配置中设置。

16. linkStyle 十六进制颜色作为最后一个属性的问题

在 linkStyle 中将十六进制颜色作为最后一个属性会导致解析错误：

flowchart LR
    A --> B
    %% BAD: hex color as last attribute
    %% linkStyle 0 stroke-width:4px,stroke:#FF69B4

    %% GOOD: hex color NOT last, or use color name
    linkStyle 0 stroke:#FF69B4,stroke-width:4px
    %% OR: linkStyle 0 stroke-width:4px,stroke:hotpink

解决方法： 将十六进制颜色放在其他属性前面，或使用 CSS 颜色名称。

17. 类图命名空间限制

关系和注释必须在命名空间块外部定义：

classDiagram
    namespace MyPackage {
        class ClassA
        class ClassB
    }
    %% Relationships OUTSIDE namespace block
    ClassA --> ClassB
    note for ClassA "This note is outside namespace"

限制： 不支持嵌套命名空间。请使用扁平结构。

18. 架构图标签字符

架构节点标签仅支持 [a-zA-Z0-9_ ]。连字符和特殊字符会导致错误：

architecture-beta
    %% BAD: service db[Cloud-Name]  (hyphen breaks)
    %% GOOD: use underscore or spaces
    service db(database)[Cloud_Name]

Mermaid v11 新功能

手绘效果

%%{init: {"look": "handDrawn"}}%%
flowchart LR
    A[Sketchy] --> B[Style]

双向箭头（时序图）

sequenceDiagram
    A <<->> B: Bidirectional
    A <<-->> B: Bidirectional dotted

配置指令

%%{init: {
    "theme": "dark",
    "flowchart": {"curve": "linear"}
}}%%
flowchart LR
    A --> B

图表类型快速参考

流程图方向

语法	方向
flowchart TB	从上到下
flowchart TD	从上到下（与 TB 相同）
flowchart BT	从下到上
flowchart LR	从左到右
flowchart RL	从右到左

节点形状

语法	形状
A[text]	矩形
A(text)	圆角矩形
A([text])	体育场形
A[[text]]	子程序
A[(text)]	圆柱体（数据库）
A((text))	圆形
A{text}	菱形
A{{text}}	六边形
A>text]	不对称形

连线类型

语法	类型
A --> B	箭头
A --- B	线条（无箭头）
A -.- B	点线
A ==> B	粗箭头
A -.-> B	点状箭头
A --text--> B	带文本的箭头
A -- text --- B	带文本的线条

子图语法

flowchart TB
    subgraph GroupName["Display Title"]
        direction LR
        A --> B
    end
    C --> GroupName

序列图要点

消息箭头类型

语法	描述
A->B	实线，无箭头
A-->B	点线，无箭头
A->>B	实线，带箭头
A-->>B	点线，带箭头
A-xB	实线，交叉端点
A-)B	实线，开放箭头（异步）

参与者定义

sequenceDiagram
    participant A as Alice
    actor B as Bob
    A->>B: Hello

激活

sequenceDiagram
    A->>+B: Request
    B-->>-A: Response

或显式指定：

sequenceDiagram
    A->>B: Request
    activate B
    B-->>A: Response
    deactivate B

控制流

sequenceDiagram
    alt Success
        A->>B: OK
    else Failure
        A->>B: Error
    end

    opt Optional
        A->>B: Maybe
    end

    loop Every minute
        A->>B: Ping
    end

    par Parallel
        A->>B: Task1
    and
        A->>C: Task2
    end

注释

sequenceDiagram
    Note right of A: Single line note
    Note over A,B: Spanning note

类图要点

类定义

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }

可见性修饰符

符号	含义
+	公有
-	私有
#	受保护
~	包级/内部

关系

语法	含义
A <|-- B	继承（B 扩展 A）
A *-- B	组合
A o-- B	聚合
A --> B	关联
A ..> B	依赖
A ..|> B	实现

基数

classDiagram
    Customer "1" --> "*" Order : places

状态图要点

基本状态

stateDiagram-v2
    [*] --> State1
    State1 --> State2: transition
    State2 --> [*]

复合状态

stateDiagram-v2
    state Parent {
        [*] --> Child1
        Child1 --> Child2
    }

选择与分叉

stateDiagram-v2
    state choice <<choice>>
    State1 --> choice
    choice --> State2: if condition
    choice --> State3: else

    state fork <<fork>>
    State4 --> fork
    fork --> State5
    fork --> State6

常见错误模式

错误 1：未加引号的特殊字符

%% BAD - breaks parsing
A[Click here (optional)]
B[User: Admin]

%% GOOD - quoted text
A["Click here (optional)"]
B["User: Admin"]

错误 2：保留字“end”

%% BAD - breaks diagram
A --> end
subgraph end

%% GOOD - quoted or capitalized
A --> End
A --> ["end"]
subgraph "End Phase"

错误 3：序列图中的分号

%% BAD - treated as line break
A->>B: key;value;data

%% GOOD - HTML entity
A->>B: key#59;value#59;data

错误 4：嵌套引号

%% BAD - quote conflict
A["Say "Hello""]

%% GOOD - use single quotes inside
A["Say 'Hello'"]
%% Or use HTML entity
A["Say #quot;Hello#quot;"]

错误 5：流程图中冒号未加引号

%% BAD - colon breaks node text
A[Step 1: Initialize]

%% GOOD - quoted
A["Step 1: Initialize"]

其他图表类型（快速入门）

ER 图

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains

甘特图

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
        Task A :a1, 2024-01-01, 30d
        Task B :after a1, 20d

饼图

pie title Distribution
    "A" : 40
    "B" : 30
    "C" : 30

Git 图

gitGraph
    commit
    branch develop
    commit
    checkout main
    merge develop

验证清单

完成 Mermaid 图表前：

1. 所有包含特殊字符的文本都已加引号
2. 没有将保留字用作节点 ID（end、default、style、class 等）
3. 没有以单个 o 或 x 开头的节点 ID
4. 序列消息中的分号使用 #59;
5. 嵌套引号使用单引号或 HTML 实体
6. 子图标题若包含 <br/> 或特殊字符，则需加引号
7. 图表类型声明正确（使用 flowchart，而非 flow-chart）
8. 注释使用 %%（不是单个 %）
9. stroke-dasharray 中的逗号使用 \, 转义
10. Frontmatter 的 --- 位于第一行（前面没有空格）
11. 思维导图避免使用 < 字符（改用单词）
12. 不要同时连接父子子图（应改为连接内部节点）
13. 只有所有节点都留在子图内部时，子图方向才可靠
14. 如果使用 ---（无箭头），请确认 Mermaid v11.5+，或使用变通方法
15. 标签中的下划线在 v11 中可能显示为斜体（请使用引号）
16. 不能在 frontmatter 中设置 maxTextSize/maxEdges（安全设置）
17. linkStyle：十六进制颜色不能作为最后一个属性（或使用颜色名称）
18. classDiagram：关系和注释放在 namespace 块之外
19. architecture-beta：标签只能使用 [a-zA-Z0-9_ ]，不能使用连字符
20. 提交前在 https://mermaid.live/ 上测试

其他资源

参考文件

有关各类图表语法的详细信息：

• references/flowchart-complete.md - 30 多种节点形状、边样式、子图嵌套
• references/sequence-complete.md - 所有消息类型、方框、中断、关键区段
• references/class-state-complete.md - 类注解、状态并发、ER 图、注释
• references/other-diagrams.md - 甘特图、饼图、Git 图、思维导图、时间线

示例文件

examples/ 中的可运行示例：

• examples/flowchart-examples.md - 常见流程图模式
• examples/sequence-examples.md - API 流程、身份验证流程模式

脚本

• scripts/validate-mermaid.sh - 基本语法验证辅助工具

外部资源

• 在线编辑器： https://mermaid.live/ - 测试和调试图表
• 官方文档： https://mermaid.js.org/intro/syntax-reference.html
• GitHub： https://github.com/mermaid-js/mermaid