Mermaid Graph 实战指南
Mermaid Graph 语法指南
涵盖 Mermaid flowchart / graph 语法的常用部分，用于绘制架构图、流程图、调用链等。
目录
基础语法
最小示例：
```mermaid
flowchart LR
A[开始] --> B{判断}
B -->|是| C[执行 A]
B -->|否| D[执行 B]
C --> E[结束]
D --> E
```
三个核心概念：
- 节点：
A[文本]，A是 ID，方括号内是显示内容 - 连线：
A --> B，A 指向 B - 标签：
A -->|文字| B，连线上加文字
graph 与 flowchart 关键字等价，新写法用 flowchart，支持的特性更多。
节点形状
| 语法 | 形状 | 常见用途 |
|---|---|---|
A[文本] |
矩形 | 流程步骤、组件 |
A(文本) |
圆角矩形 | 操作 |
A((文本)) |
圆形 | 起止点 |
A{文本} |
菱形 | 判断 |
A[/文本/] |
平行四边形 | 输入/输出 |
A[(文本)] |
圆柱 | 数据库、存储 |
A{{文本}} |
六边形 | 准备步骤 |
A(((文本))) |
双圈 | 终止节点 |
A[[文本]] |
子程序 | 子过程、模块 |
示例：
```mermaid
flowchart LR
Start((开始)) --> Input[/用户输入/]
Input --> Check{合法?}
Check -->|是| DB[(数据库)]
Check -->|否| Err[/错误提示/]
DB --> End(((结束)))
```
连线
线型
| 语法 | 含义 |
|---|---|
A --> B |
实线箭头 |
A --- B |
实线无箭头 |
A -.-> B |
虚线箭头 |
A ==> B |
粗实线箭头 |
A ~~~ B |
隐形连线（仅用于布局） |
标签
A -->|HTTP 请求| B
A -- HTTP 请求 --> B
A -.->|超时回退| B
多目标
A --> B & C & D # A 同时指向 B、C、D
A & B --> C # A、B 都指向 C
A --> B --> C # 链式
节点较多时用 & 可减少行数。
布局方向
flowchart TB # 自上而下（默认）
flowchart TD # 同 TB
flowchart BT # 自下而上
flowchart LR # 从左到右
flowchart RL # 从右到左
经验：流程图用 LR，分层架构图用 TB。子图内可用 direction LR 单独控制方向。
子图
flowchart TB
subgraph Frontend["前端层"]
direction LR
Web[Web]
App[App]
end
subgraph Backend["后端层"]
API[API Gateway]
Svc[Service]
API --> Svc
end
Frontend --> Backend
要点：
subgraph ID["显示标题"]，ID 用于连线，标题可含中文和空格- 子图必须以
end结尾 - 可对子图整体连线（
Frontend --> Backend），避免节点间 N×M 连线
样式
三种方式
style：单个节点或子图classDef+class：批量样式（推荐）linkStyle：边样式（按声明顺序索引）
classDef 用法
classDef apiNode fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
classDef dbNode fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
class A,B,C apiNode
class DB1,DB2 dbNode
class 语句中元素之间只能有一个空格，多空格会触发解析错误。
样式属性
| 属性 | 示例 | 说明 |
|---|---|---|
fill |
#dbeafe |
填充色 |
stroke |
#3b82f6 |
边框色 |
stroke-width |
2px |
边框粗细 |
stroke-dasharray |
5 5 |
虚线 |
color |
#1e3a8a |
文字颜色 |
linkStyle
linkStyle 0 stroke:#22c55e,stroke-width:3px
linkStyle 0,2,4 stroke:#ef4444
linkStyle default stroke:#64748b,stroke-width:1.5px
边索引从 0 开始，按声明顺序计算。
主题与字体
```mermaid
%%{init: {'theme':'base','themeVariables':{'fontFamily':'Microsoft YaHei, sans-serif','fontSize':'14px'}}}%%
flowchart LR
A --> B
```
主题可选：default、base、dark、forest、neutral。
常见报错
class 语句多空格
class LC,DC cacheNode # 报错
class LC,DC cacheNode # 正确
节点文本含特殊字符
A[a < b] # 解析失败
A["a < b"] # 双引号包裹
A[a < b] # HTML 实体
需注意的字符：< > " ( ) #。建议节点文本统一加双引号。
子图标题含括号
subgraph Cache(缓存) # 错误
subgraph Cache["缓存（性能关键）"] # 正确
中文 ID
节点 ID 应使用 ASCII。文本可以是中文：
缓存 --> 数据库 # 不推荐
Cache --> DB # 推荐
Markdown 引用图片时的括号
文件名含 () 时，markdown 图片语法会冲突：
.png) # 失效
.png>) # 用尖括号包裹
classDef 的 font-size
部分版本不支持 font-size。需要加粗或放大文字时，用 HTML 标签更稳妥：
A["<b>重要节点</b><br/><i>说明</i>"]
模板
以下模板用
```mermaid单层代码块呈现，markdown 编辑器可直接渲染图形；查看源码请打开本文件原文。
五层分层架构（含外部协作系统）
通用模板：login → 前端 → API → 服务 → 存储，外部系统以虚线区分边界。
所有节点名称为占位符，使用时按实际场景替换。
graph TB
classDef userTier fill:#FFF8E1,stroke:#F9A825,stroke-width:2px,color:#5D4037
classDef page fill:#E3F2FD,stroke:#1565C0,stroke-width:1.5px,color:#0D47A1
classDef core fill:#F3E5F5,stroke:#7B1FA2,stroke-width:2px,color:#4A148C
classDef service fill:#E8F5E9,stroke:#2E7D32,stroke-width:1.5px,color:#1B5E20
classDef storage fill:#FFF3E0,stroke:#EF6C00,stroke-width:1.5px,color:#E65100
classDef external fill:#FFEBEE,stroke:#C62828,stroke-width:1.5px,color:#B71C1C
subgraph L0 ["① login"]
direction LR
USER(["Actor A<br/>说明"]):::userTier
end
subgraph L1 ["② 前端表现层"]
direction LR
PG1["Page Group A<br/>Page1 · Page2 · Page3"]:::page
PG2["Page Group B<br/>Page1 · Page2 · Page3"]:::page
end
API[["③ API 接口层<br/>职责说明 1 · 职责说明 2 · 职责说明 3"]]:::core
subgraph L3 ["④ 服务层"]
direction LR
S1["Service A"]:::service
S2["Service B"]:::service
S3["Service C"]:::service
end
subgraph L4 ["⑤ 存储层"]
direction LR
DB[("Storage A<br/>entity_a · entity_b · entity_c")]:::storage
CACHE[("Storage B")]:::storage
end
subgraph EXT ["⑥ 外部系统"]
direction TB
EXT1["External A<br/>职责描述"]:::external
EXT2["External B<br/>职责描述"]:::external
EXT3["External C<br/>职责描述"]:::external
end
L0 --> L1
PG1 --> API
PG2 --> API
API --> S1
API --> S2
API --> S3
S1 --> DB
S2 --> DB
S3 --> DB
S2 --> CACHE
API -. action 1 .-> EXT1
S2 -. action 2 .-> EXT2
S3 -. action 3 .-> EXT3
L3 ~~~ EXT
占位符约定：
| 占位符 | 替换为 |
|---|---|
Actor A |
系统使用方角色 |
Page Group A/B |
前端按功能域聚合的页面分组 |
职责说明 |
API 层关注点（如 鉴权 / 校验 / 异常 / 日志） |
Service A/B/C |
后端按域切分的服务 |
Storage A/B |
持久化或缓存组件 |
entity_* |
数据实体或表名 |
External A/B/C |
外部依赖系统 |
action * |
与外部系统的交互动作 |
要点：
classDef按层着色，每层一个色系- 每层用
subgraph包裹，内部direction LR横向排列同层组件 - API 层用子程序形状
[[ ]]突出"统一入口" - 存储层用圆柱
[( )]，外部系统用普通矩形 - 主链路实线
-->，外部协作虚线-.->并标注交互动作 - 末尾
L3 ~~~ EXT是隐形连线，作为布局锚点让外部系统与服务层 rank 对齐
三层架构
flowchart TB
subgraph FE["前端层"]
Web[Web 端]
Mob[移动端]
end
subgraph BE["后端层"]
GW[API 网关]
Svc[业务服务]
GW --> Svc
end
subgraph DATA["数据层"]
DB[(主库)]
Cache[(缓存)]
MQ[/消息队列/]
end
FE --> BE
BE --> DATA
classDef fe fill:#dbeafe,stroke:#3b82f6
classDef be fill:#dcfce7,stroke:#22c55e
classDef data fill:#fef3c7,stroke:#f59e0b
class Web,Mob fe
class GW,Svc be
class DB,Cache,MQ data
决策流程
flowchart LR
Start((开始)) --> Input[/接收请求/]
Input --> Auth{已认证?}
Auth -->|否| Reject[/拒绝/]
Auth -->|是| Limit{超限?}
Limit -->|是| Throttle[/限流/]
Limit -->|否| Process[处理]
Process --> Resp[/返回结果/]
Reject --> End(((结束)))
Throttle --> End
Resp --> End
微服务调用链
flowchart LR
Client((Client)) ==> GW[API Gateway]
GW ==> Auth[Auth Svc]
GW ==> User[User Svc]
GW ==> Order[Order Svc]
User -.-> UDB[(User DB)]
Order -.-> ODB[(Order DB)]
Order -.-> MQ[/Kafka/]
classDef svc fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
classDef store fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
class GW,Auth,User,Order svc
class UDB,ODB,MQ store
状态机
flowchart LR
Draft((草稿)) --> Submit[提交]
Submit --> Review{审核}
Review -->|通过| Published(((已发布)))
Review -->|驳回| Draft
Published --> Archive(((归档)))
故障排查树
flowchart TB
Issue{服务异常?} -->|是| Check1{CPU 高?}
Check1 -->|是| Action1[扩容 / 限流]
Check1 -->|否| Check2{内存高?}
Check2 -->|是| Action2[内存泄漏排查]
Check2 -->|否| Check3{磁盘满?}
Check3 -->|是| Action3[清理日志]
Check3 -->|否| Action4[查日志 / 链路追踪]
渲染工具
| 场景 | 工具 |
|---|---|
| 在线预览 | mermaid.live |
| VS Code | 插件 Markdown Preview Mermaid Support |
| GitHub / GitLab | 原生支持 mermaid 代码块 |
| Typora | 内置渲染 |
| Obsidian | 内置渲染 |
| 命令行导出 | @mermaid-js/mermaid-cli（mmdc） |
CLI 用法：
npm install -g @mermaid-js/mermaid-cli
mmdc -i diagram.mmd -o diagram.png -w 1920 -H 1080
速查
flowchart LR # 方向
A[矩形] --> B(圆角) # 形状 + 实线
B --> C{菱形} # 判断
C -->|标签| D[(数据库)] # 标签 + 圆柱
D -.-> E((圆)) # 虚线
A & B --> C # 多对一
subgraph G["分组"] # 子图
direction TB
X --> Y
end
classDef hi fill:#fef3c7 # 样式定义
class A,B hi # 应用样式（单空格）
linkStyle 0 stroke:#22c55e # 边样式
浙公网安备 33010602011771号