Mermaid Flowchart 进阶：从节点形状到 Subgraph 拆图

Mermaid 的 Flowchart（流程图）是它最招牌的功能——比 PlantUML 的 Activity 图更接近手绘风格，上手更快、样式更灵活。这一篇把它讲透。

为什么选 Flowchart 而不是 Activity 图

PlantUML 有 activity diagram（活动图），但它是 UML 风格的——起点/终点用实心圆、分叉用菱形、并行用 fork/join。画出来是标准的 UML 流程图，严谨但刻板。

Mermaid Flowchart 是手绘风格——方框、菱形、圆柱、 stadium 形……想画什么形状就画什么，不受 UML 语义约束。适合：

业务流程图（不是软件建模）
决策树
架构拓扑
文档里的示意图

一、最小例子

1 2	flowchart LR A --> B

flowchart 是关键字，后面跟 LR（left→right）指定方向
节点默认是圆角矩形
--> 是带箭头的边

二、方向（Direction）

关键字	含义
`TB`	Top → Bottom（从上到下）
`TD`	Top → Down（同 TB，alias）
`BT`	Bottom → Top（从下到上）
`LR`	Left → Right（从左到右）
`RL`	Right → Left（从右到左）

1 2	flowchart TB 顶部 --> 中间 --> 底部

1 2	flowchart RL 右侧 --> 中间 --> 左侧

建议：默认用 TB（从上到下）——符合中文阅读习惯。LR 适合流程步骤多但层级浅的场景。

三、节点形状

Mermaid 支持 10+ 种节点形状，用 [text] 语法组合：

3.1 默认节点（圆角矩形）

A[这是圆角矩形]

3.2 圆角矩形（Stadium）

A(这是圆角矩形)

3.3 体育场形（Subroutine）

1	A[[这是体育场形]]

3.4 菱形（Decision）

A{这是菱形}

3.5 圆柱（Database）

A[(这是圆柱)]

3.6 圆形

A((这是圆形))

3.7 六边形

1	A{{这是六边形}}

3.8 平行四边形（Data）

1	A[/这是平行四边形/]

3.9 梯形（Input）

1	A[/A 这是梯形\]

3.10 完整形状对照表

flowchart LR
    subgraph 形状对照
        direction LR
        A[圆角矩形] --> B(体育场)
        B --> C[[圆柱]]
        C --> D{菱形}
        D --> E((圆形))
        E --> F{{六边形}}
        F --> G[/平行四边形/]
        G --> H[/A 梯形\]
    end

注意：同一个 flowchart 里只能有一个 direction 声明（第一个出现的位置），Subgraph 内部可以单独设 direction。

四、边的类型和样式

4.1 基本边

语法	含义
`A --> B`	实线箭头
`A --- B`	实线无箭头
`A -.-> B`	虚线箭头
`A -.坚持.-> B`	虚线箭头（加粗点）
`A ==> B`	加粗箭头
`A -- 标签 --> B`	边加文字
`A --- 标签 --- B`	边加文字（无箭头）

4.2 链式写法

1 2	flowchart LR A --> B --> C --> D

4.3 多条出边（分叉）

flowchart TD
    开始 --> 判断{是否成功}
    判断 -->|是| 成功
    判断 -->|否| 失败
    判断 -->|重试| 重试

注意 |是| 这样的语法——标签写在两条边符号中间：-->|标签| 目标。

4.4 汇聚（多条入边）

flowchart LR
    A --> C
    B --> C
    C --> D

4.5 虚线样式

flowchart LR
    A -.-> B
    B -.坚持.-> C
    C ==> D

-.坚持.-> 的 . 越多越粗。

4.6 边加箭头方向

1
2
3

flowchart LR
    A <--> B
    C <--> D

<--> 是双向箭头。

4.7 边的颜色和粗细

flowchart LR
    A -- 红色粗线 --> B
    C --"#red;bold"--> D
    E == 蓝色加粗 ==> F

在 -- 后面加 "#颜色;粗细" 可以给单条边单独着色。

五、Subgraph（子图分组）

Subgraph 是 Flowchart 最强大的功能——把一组节点包在一个带标签的框里，用于表示子系统、模块、部门、泳道。

5.1 基本 Subgraph

flowchart TB
    subgraph 前端
        A[Vue] --> B[Router]
    end
    subgraph 后端
        C[Node] --> D[Database]
    end
    A --> C

5.2 带 ID 的 Subgraph

flowchart TB
    subgraph clusterFrontend [前端模块]
        A[Vue] --> B[Pinia]
    end
    subgraph clusterBackend [后端模块]
        C[API] --> D[(DB)]
    end
    B --> C

Subgraph ID 用 subgraph 名字 [显示文本] 格式。cluster 前缀是可选的装饰符。

5.3 Subgraph 内部 direction

flowchart TB
    subgraph 登录流程
        direction LR
        输入 --> 验证 --> 成功
    end

Subgraph 内部可以用 direction LR 覆盖全局方向。

5.4 实战：电商下单流程

flowchart TD
    subgraph 客户端
        A[浏览商品] --> B[加入购物车]
        B --> C[提交订单]
    end
    subgraph 服务端
        D[接收订单] --> E{库存充足?}
        E -->|是| F[扣减库存]
        E -->|否| G[返回缺货]
        F --> H[创建订单记录]
    end
    subgraph 支付
        H --> I{支付成功?}
        I -->|是| J[发货]
        I -->|否| K[取消订单]
    end
    C --> D
    J --> L[用户确认收货]

三个 Subgraph 清晰地划分了职责边界，画出来比一个大平铺图好读 10 倍。

六、节点 ID 命名规则

6.1 可以用什么

字母：A, node1
数字：1, 2, step3
中文：开始, 判断, 结束（不需要引号）
混合：userLogin, order_submit

6.2 不能用什么

空格：A --> B C 会把 B C 解析成两个节点，正确的是 B --> C
逗号、分号、#号——这些在 Mermaid 里是特殊字符
单独的引号：要用引号包起来

6.3 含空格或特殊字符的节点名

1
2
3

flowchart LR
    "节点 A" --> "节点 B"
    "特殊字符 #1" --> "分号;也不行"

6.4 常见报错

报错	原因	修复
`Parse error in "..."`	节点 ID 有空格	用引号包起来 `"节点 A"`
`Duplicated id`	两个节点用了同一个 ID	改用不同 ID
`Invalid edge`	边的两端 ID 不存在	检查拼写

七、样式和主题

7.1 内联样式（单节点）

1
2
3

flowchart LR
    A --> B
    style A fill:#f9f,stroke:#333,stroke-width:4px

style 指令可以给节点单独设置填充色、边框颜色、边框宽度。

7.2 边的样式

flowchart LR
    A --> B
    B --> C
    classDef highlight fill:#f96,stroke:#333,stroke-width:4px
    class B highlight

classDef 定义一个样式类，class 把类应用到节点上。比 style 更干净，适合多个节点用同一套样式。

7.3 Mermaid 内置主题色

在 mermaid 代码块里加 %%{init: {'theme': 'dark'}}%% 可以切换主题：

1
2
3

%%{init: {'theme': 'dark'}}%%
flowchart TD
    A[深色主题] --> B[圆角矩形]

支持的主题：default, forest, dark, neutral, base。

7.4 完整样式示例

flowchart TD
    subgraph 认证
        A{登录?} -->|是| B[获取 Token]
        A -->|否| C[跳转登录页]
    end
    
    subgraph 数据层
        B --> D[(查询数据库)]
        D --> E{有数据?}
        E -->|是| F[返回数据]
        E -->|否| G[返回空]
    end
    
    style A fill:#ff6b6b,stroke:#333,stroke-width:2px
    style E fill:#ffd93d,stroke:#333,stroke-width:2px
    style D fill:#6bcb77,stroke:#333,stroke-width:2px

八、和 PlantUML Activity 图的对比

功能	Mermaid Flowchart	PlantUML Activity
节点形状	10+ 种，可混用	UML 标准形状（有限）
Subgraph/分区	✅ 支持	`partition` 支持，但不支持嵌套
方向	4 种（TB/LR/RL/BT）	4 种（TD/LR/DT/RL）
样式定制	`style` + `classDef`	`style` 支持但较繁琐
中文支持	✅ 好	✅ 好
手绘风格	✅ 是	❌ 否（UML 严谨风格）

简单说：业务文档、决策树、示意图 → Mermaid Flowchart；软件建模、流程规范 → PlantUML Activity。

九、Mermaid 独占功能（PlantUML 没有）

Mermaid Flowchart 有几个 PlantUML Activity 完全不具备的能力：

9.1 Git Graph

Mermaid 独有，不需要 PlantUML 插件：

gitGraph
    commit id: "初始提交"
    commit id: "添加功能 A"
    branch feature
    checkout feature
    commit id: "开发中"
    checkout main
    commit id: "修复 bug"
    merge feature id: "合并分支"

9.2 Requirement Diagram

需求追踪图，PlantUML 没有原生支持：

requirementDiagram
    
    requirement TestReq {
        id: 1
        text: "系统必须在 100ms 内响应"
        risk: high
        verifymethod: test
    }
    
    element entity {
        type: simulation
    }
    
    entity --> TestReq

9.3 Pie Chart

饼图，纯声明式：

pie title 编程语言使用分布
    "JavaScript" : 42
    "Python" : 27
    "TypeScript" : 18
    "Go" : 8
    "其他" : 5

这三个图类型完全不需要 PlantUML，Mermaid 一行搞定。

十、常见报错与 Debug

10.1 节点 ID 重复

1
2
3

flowchart LR
    A --> B
    A --> C

A 被用了两次——这是合法的（可以有多条从 A 出发的边）。但如果写成两个不同节点用了同一个 ID，就会报错。

10.2 循环引用导致渲染失败

flowchart LR
    A --> B
    B --> C
    C --> A

有循环是可以的，但如果边太多太乱，Mermaid 会报 节点太多，请简化。

10.3 Subgraph 里 direction 位置错误

direction 只能在 Subgraph 第一行声明，放在节点定义之后无效：

flowchart TB
    subgraph 示例
        A --> B
        direction LR
    end

上面 direction LR 在节点之后，无效。正确的写法是：

flowchart TB
    subgraph 示例
        direction LR
        A --> B
    end

小结

Mermaid Flowchart 核心记住 5 点：

方向：TB（从上到下）默认够用
形状：[矩形] (圆角) {菱形} ((圆形)) [[圆柱]] ——形状决定语义
边：--> 是箭头，--- 是线，-.-> 是虚线，==> 是粗线
Subgraph：分组是拆解复杂图的核心武器
Style：classDef 定义类，style 单独染色，主题切换加 %%{init:{'theme':'dark'}}%%

PlantUML 没有原生的 Flowchart，只有 Activity 图——两者定位不同。画业务流、决策树、示意图，Mermaid Flowchart 是首选。