Mermaid 使用指南

本文档介绍

1. 如何在 VSCode 中配置 Mermaid 语法预览环境，
2. 如何安装 Mermaid CLI，以及如何将 .mmd 文件转换为 PNG 图片。
3. mermaid 语法介绍及示例

---

1. VSCode 配置 Mermaid 预览

1.1 安装插件

在 VSCode 扩展市场搜索并安装以下插件（任选其一即可）：

插件名	扩展 ID	说明
Markdown Preview Mermaid Support	bierner.markdown-mermaid	在 Markdown 预览中渲染 Mermaid 图表（推荐）
Mermaid Preview	vstirbu.vscode-mermaid-preview	直接预览 .mmd 文件

命令行安装：

# 安装 Markdown 预览支持（推荐）
code --install-extension bierner.markdown-mermaid

# 安装 .mmd 文件直接预览
code --install-extension vstirbu.vscode-mermaid-preview

1.2 在 Markdown 中使用 Mermaid

在 .md 文件中使用代码块标注 mermaid，安装插件后可在预览面板（Ctrl+Shift+V）中看到渲染结果：

```mermaid
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> A
```

1.3 直接预览 .mmd 文件

安装 vstirbu.vscode-mermaid-preview 后，打开 .mmd 文件，使用命令面板（Ctrl+Shift+P）执行：

Mermaid: Open Preview to the Side

或右键文件选择 Preview Diagram。

---

2. 安装 Mermaid CLI

Mermaid CLI（mmdc）可将 .mmd 文件批量转换为 PNG、SVG、PDF 等格式。

2.1 前置条件

Mermaid CLI 依赖 Node.js（建议 v16+）：

# 检查 Node.js 版本
node --version

# 若未安装，使用 nvm 安装（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts

2.2 全局安装

npm install -g @mermaid-js/mermaid-cli

或（国内尝试用下面这个镜像）

    npm install -g @mermaid-js/mermaid-cli --verbose --registry=https://registry.npmmirror.com

如果失败可以这样，或参考步骤2.4：

npm cache clean --force
rm -rf /home/longbin/.cache/puppeteer

export PUPPETEER_SKIP_DOWNLOAD=true
# npm install -g @mermaid-js/mermaid-cli --verbose
npm install -g @mermaid-js/mermaid-cli --verbose --registry=https://registry.npmmirror.com

# install chrome manually
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo apt install ./google-chrome-stable_current_amd64.deb
rm google-chrome-stable_current_amd64.deb

# set env
which google-chrome
export PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome
echo "export PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome" >> ~/.bashrc
echo "please reload the env by: source ~/.bashrc"

验证安装：

mmdc --version

2.3 项目本地安装（推荐用于 CI/CD）

# 在项目根目录
npm install --save-dev @mermaid-js/mermaid-cli

# 使用 npx 调用
npx mmdc --version

2.4 Linux 无头浏览器依赖

Mermaid CLI 内部使用 Puppeteer 驱动 Chromium。Linux 服务器上需要安装 Chromium 依赖：

# Ubuntu / Debian
sudo apt-get update
sudo apt-get install -y chromium-browser

# 如果 Puppeteer 无法找到 Chromium，手动指定路径
export PUPPETEER_EXECUTABLE_PATH=$(which chromium-browser)

---

3. 将 .mmd 文件转换为 PNG

3.1 基本转换

# 单文件转换
mmdc -i diagram.mmd -o diagram.png

# 指定输出格式（svg / png / pdf）
mmdc -i diagram.mmd -o diagram.svg

# 指定图像宽度（默认 800px）
mmdc -i diagram.mmd -o diagram.png -w 1920 -H 1080

3.2 常用参数

参数	说明	示例
-i <file>	输入的 .mmd 文件	-i arch.mmd
-o <file>	输出文件路径	-o arch.png
-t <theme>	主题：default / dark / forest / neutral	-t dark
-b <color>	背景色（CSS 颜色或 transparent）	-b transparent
-w <px>	图像宽度（像素）	-w 1200
-H <px>	图像高度（像素）	-H 800
-s <scale>	缩放比例（默认 1）	-s 2
-c <config>	自定义 Mermaid 配置文件（JSON）	-c mermaid.json
--puppeteerConfigFile	Puppeteer 配置文件	--puppeteerConfigFile pp.json

3.3 批量转换（Shell 脚本）

#!/bin/bash
# convert-all-mmd.sh — 将 docs/ 下所有 .mmd 文件转为 PNG
set -e

INPUT_DIR="docs"
OUTPUT_DIR="docs/images"
THEME="default"

mkdir -p "$OUTPUT_DIR"

for mmd_file in "$INPUT_DIR"/*.mmd; do
    [ -f "$mmd_file" ] || continue
    base=$(basename "$mmd_file" .mmd)
    output="$OUTPUT_DIR/${base}.png"
    echo "Converting: $mmd_file -> $output"
    mmdc -i "$mmd_file" -o "$output" -t "$THEME" -b white
done

echo "Done. Output in $OUTPUT_DIR/"

运行脚本：

chmod +x convert-all-mmd.sh
./convert-all-mmd.sh

3.4 在沙盒/CI 环境中运行（无 GPU）

Puppeteer 需要 --no-sandbox 参数才能在 Docker 或 CI 环境中运行，通过 Puppeteer 配置文件传入：

// puppeteer-config.json
{
  "args": ["--no-sandbox", "--disable-setuid-sandbox"]
}

mmdc -i diagram.mmd -o diagram.png \
     --puppeteerConfigFile puppeteer-config.json

---

4. Mermaid 图表示例

4.1 流程图（Flowchart）

4.2 序列图（Sequence Diagram）

4.3 类图（Class Diagram）

---

5. Mermaid 语法速查表

5.1 图表类型总览

图类型	关键字	用途
流程图	graph / flowchart	算法流程、逻辑分支
序列图	sequenceDiagram	组件交互时序
类图	classDiagram	类的继承/组合关系
状态图	stateDiagram-v2	状态机、有限状态自动机
实体关系图	erDiagram	数据库表结构
甘特图	gantt	项目进度、里程碑
饼图	pie	占比分布
Git 图	gitGraph	分支合并历史
思维导图	mindmap	层级概念整理
时间线	timeline	事件时间轴

---

5.2 流程图语法速查

方向关键字：TD（上到下）、LR（左到右）、BT（下到上）、RL（右到左）

注释：%% 这是注释

子图：

subgraph 子图名称
    A --> B
end

---

5.2b 流程图（Flowchart）完整高级语法

全部节点形状

节点形状速查：

写法	形状	常见用途
[文字]	矩形	处理步骤
(文字)	圆角矩形	一般节点
([文字])	体育场/pill	开始/结束
[[文字]]	双线矩形	子程序调用
[(文字)]	圆柱	数据库/存储
((文字))	圆形	连接点
{文字}	菱形	条件判断
{{文字}}	六边形	准备/配置
[/文字/]	平行四边形右斜	输入
[\文字\]	平行四边形左斜	输出
[/文字\]	梯形上宽
[\文字/]	梯形下宽

---

全部箭头 / 连线类型

写法	类型	说明
-->	实线箭头	标准流向
--->	加长实线箭头	跨越更多层
-.->	虚线箭头	可选/弱依赖
==>	粗实线箭头	强调流向
--o	圆头	聚合关系
--x	X 头	阻止/禁止
<-->	双向箭头	双向流
o--o	双圆头	双向聚合
x--x	双 X 头	双向禁止
-- "标签" -->	带标签实线	标准写法
`–>	“标签”	`

---

链式连接 + 多目标

---

子图（Subgraph）+ 嵌套 + 跨子图连线

---

点击事件 + 超链接

语法：

click 节点ID "URL" "Tooltip" _blank
click 节点ID callback "Tooltip"

---

样式（classDef + style）

语法	说明
classDef 名称 fill:#hex,stroke:#hex,color:#hex	定义样式类
:::样式名	节点行内应用
class 节点1,节点2 样式名	批量应用
style 节点 属性:值	直接设置单个节点

支持的 CSS 属性：fill / stroke / stroke-width / color / stroke-dasharray / rx / ry

---

图级配置（frontmatter / init 指令）

常用主题：default / base / dark / forest / neutral

或在 mmdc 命令行中指定：

mmdc -i input.mmd -o output.svg --theme forest

---

5.2a 序列图（Sequence Diagram）完整语法

消息类型速查：

符号	线型	箭头	含义
A ->> B	实线	实心	同步调用
A -->> B	虚线	实心	返回值 / 响应
A -x B	实线	×	消息丢失
A --x B	虚线	×	丢失响应
A -) B	实线	开放	异步消息
A --) B	虚线	开放	异步响应

控制块速查：

块类型	语法	用途
激活框	activate X / deactivate X	标记处理期间
循环	loop 说明 ... end	重复执行
条件	alt 说明 ... else ... end	if/else 分支
可选	opt 说明 ... end	可选执行
并行	par ... and ... end	并发执行
异常	critical ... option ... end	try/catch 风格
背景色	rect rgb(r,g,b) ... end	区域高亮
注解	note right of X: 文字	标注说明
自调用	A ->> A: 方法名	递归 / 内部调用
销毁	destroy X	参与者生命周期结束

---

5.3 状态图（State Diagram）

关键语法：

• [*] — 起始/终止伪状态
• A --> B : 事件标签
• state "描述" as 别名
• note right of 状态名 ... end note
• state 并发状态 { ... || ... } — 并发状态（fork/join）

---

5.4 实体关系图（ER Diagram）

关键语法：

• ||--|| 一对一，||--o{ 一对多，}o--o{ 多对多
• PK 主键，FK 外键，UK 唯一键
• {字段类型 字段名 约束} 定义属性

---

5.5 甘特图（Gantt Chart）

关键语法：

• dateFormat YYYY-MM-DD — 日期格式
• section 分区名 — 分组
• :done 已完成，:active 进行中，:crit 关键路径，:milestone 里程碑
• after 任务id — 依赖关系
• excludes weekends — 排除周末

---

5.6 Git 图（Git Graph）

关键语法：

• commit id: "说明" — 提交
• branch 分支名 — 创建分支
• checkout 分支名 — 切换分支
• merge 分支名 — 合并
• tag: "标签" — 打标签

---

5.7 饼图（Pie Chart）

---

5.8 思维导图（Mind Map）

---

5.9 类图（Class Diagram）完整语法

关系符号速查：

符号	关系	含义
<|--	继承	子类 extends 父类
<|..	实现	类 implements 接口
*--	组合	强拥有，生命周期一致
o--	聚合	弱拥有，独立生命周期
-->	关联	单向关联（有引用）
--	关联	双向关联
..>	依赖	临时使用（参数/局部变量）
..	依赖	双向依赖

类注解关键字：<<interface>> / <<abstract>> / <<enum>> / <<singleton>> / <<service>>

---

5.9a 类图——完整补充语法

基数 / 多重性（Cardinality / Multiplicity）

在关系箭头两端可以标注多重性，格式 "基数" 加在箭头符号前后：

常用基数写法："1" "0..1" "1..*" "0..*" "n" "1..n"

---

枚举（Enum）

---

命名空间（Namespace）

Mermaid 10.1+ 支持 namespace 块对类进行分组：

---

注解（Note）

为类或关系添加文字说明：

语法：note for ClassName "文字内容\n支持换行"

---

图方向（Direction）

方向选项：direction TB（默认，从上到下）、direction BT、direction LR、direction RL

---

完整方法签名（参数 + 返回值）

格式：+methodName(paramName type, ...) ReturnType
类型直接用英文单词（不用 C++ 语法），* 指针写成 type_ptr 或省略。

---

样式 / 高亮（CSS 自定义）

语法：classDef 样式名 fill:#色值,stroke:#边框色,color:#字体色
应用：class 类名:::样式名 { ... } 或 class ClassName:::styleName（不含成员时）

---

5.10 C4 模型图（架构视图）

Mermaid 支持 C4 Context / Container / Component 三层架构图：

注意：C4 图需安装 @mermaid-js/mermaid-cli ≥ 10.x 才能正确渲染。

---

5.11 时间线图（Timeline）

---

5.12 需求图（Requirement Diagram）

用于描述系统需求及其与设计元素的追溯关系（较新特性，需 Mermaid 9+）：

⚠️ requirementDiagram 已知语法陷阱（Mermaid 词法器限制）

问题	错误示例	正确写法
ID 不能含连字符	id: REQ-001	id: REQ_001（用下划线）
text: 值不能含连字符	text: multi-thread calls	text: multithread calls
text: 值不要加引号	text: "系统必须..."	text: plain ASCII text
关系箭头必须用 ->	A - satisfies - B	A - satisfies -> B

根因：词法器将 - 识别为关系运算符 token，在 ID、属性值、关系行中均适用；带引号的多字节（CJK）字符串在不同 Mermaid 版本中解析不一致。

---

5.13 块图（Block Diagram）完整语法

Mermaid 10.3+ 引入的 block-beta 图，适合绘制系统模块分组与数据流：

---

基本块 + columns 布局

---

节点形状

形状速查：

写法	形状	用途
["文字"]	矩形	模块/组件
(["文字"])	圆角矩形	流程节点
(("文字"))	圆形	起止点
[/"文字"/]	平行四边形（斜右）	输入
[\"文字"\]	平行四边形（斜左）	输出
{{"文字"}}	菱形	判断
[["文字"]]	双线矩形	子程序

---

嵌套块 + 样式

---

箭头类型

---

替代方案：graph TB + subgraph（兼容旧版）

当 Mermaid < 10.3 时，用 graph + subgraph 实现模块图：

subgraph 关键语法：

subgraph ID["显示标题"]
    direction LR    %% 可覆盖子图内部方向
    节点定义...
end

注意：block-beta 需要 Mermaid 10.3+；旧版可用 graph TB + subgraph 代替。
subgraph 内节点可参与外部箭头；block 内节点只通过父块 ID 参与外部连接。

---

6. 参考链接

• Mermaid 官方文档
• Mermaid CLI GitHub
• VSCode Markdown Preview Mermaid Support
• VSCode Mermaid Preview
• Mermaid Live Editor（在线预览）