3.1 Markdown 中直接写#

最常见写法是在 Markdown 代码块中使用 mermaid 语言标识：

1
```mermaid
2
flowchart TD
3
  A[开始] --> B{是否通过?}
4
  B -- 是 --> C[结束]
5
  B -- 否 --> D[修复问题]
6
  D --> B
7
```

如果平台支持 Mermaid，这段代码会被渲染成图。如果平台不支持，只会显示为普通代码块。

3.2 HTML 页面中使用#

浏览器中可以通过 Mermaid 包或 CDN 初始化：

1
<pre class="mermaid">
2
flowchart TD
3
  A[Start] --> B[End]
4
</pre>
5

6
<script type="module">
7
  import mermaid from "https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs";
8
  mermaid.initialize({ startOnLoad: true });
9
</script>

说明：

3.3 Mermaid Live Editor#

官方提供 Mermaid Live Editor，可用于：

• 快速验证语法。
• 复制 SVG 或 PNG。
• 调试报错位置。
• 分享图表链接。

适合先在 Live Editor 中调通，再放入文档或博客。

3.4 Mermaid CLI#

Mermaid CLI 包名是 @mermaid-js/mermaid-cli，命令常见为 mmdc。

安装：

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

把 .mmd 导出为 SVG：

1
mmdc -i diagram.mmd -o diagram.svg

导出 PNG：

1
mmdc -i diagram.mmd -o diagram.png

导出 PDF：

1
mmdc -i diagram.mmd -o diagram.pdf

CLI 适合以下场景：

6.1 基本方向#

方向含义：

选择建议：

• 流程步骤多：优先 TD。
• 模块依赖或数据流：优先 LR。
• 层级结构：优先 TD。
• 输入到输出的管线：优先 LR。

6.2 节点形状#

常见写法：

6.3 连线#

连线建议：

6.4 子图 Subgraph#

子图适合表达：

• 系统边界。
• 模块分层。
• 前后端分离。
• 微服务分组。
• 流程阶段。

6.5 流程图实战：登录流程#

注意：

• 判断节点尽量只写问题，不写太长句子。
• 边上的文字写判断结果，如“是/否”“成功/失败”。
• 每个节点只表达一个动作。

7.1 基本语法#

常见箭头：

7.2 激活条#

激活条表示某个参与者正在处理任务。复杂调用链中建议使用，但不要滥用。

7.3 条件、循环和并行#

常见控制块：

7.4 时序图实战：Token 刷新#

8.1 基本类定义#

可见性符号：

8.2 类之间关系#

关系符号：

8.3 使用建议#

• Mermaid 类图适合文档说明，不适合替代 UML 专业建模工具。
• 不要把所有字段、方法都塞进去，只保留理解关系所需的核心成员。
• 对领域模型，重点表达实体关系和聚合边界。
• 对代码结构，重点表达接口、实现类、依赖方向。

9.1 基本语法#

9.2 复合状态#

9.3 状态图使用建议#

• 状态名用名词或形容词，如“待支付”“运行中”“已完成”。
• 边上的文字写触发事件，如“支付成功”“超时”“重试”。
• 如果状态超过 10 个，考虑拆成多个状态图。
• 不要把流程图和状态图混用：流程图关注步骤，状态图关注状态迁移。

20.1 代码块内初始化配置#

Mermaid 支持在图表前通过 init 指令配置主题等参数：

1
```mermaid
2
%%{init: {"theme": "neutral"}}%%
3
flowchart LR
4
  A[输入] --> B[处理] --> C[输出]
5
```

常用主题：

20.2 自定义主题变量#

常见主题变量：

20.3 安全等级 securityLevel#

securityLevel 会影响 HTML 标签、链接、点击事件等能力。文档平台通常会采用较严格的安全策略，防止脚本注入。

常见策略：

21.1 GitHub#

GitHub Markdown 支持在 fenced code block 中渲染 Mermaid 图表。写法如下：

1
```mermaid
2
flowchart LR
3
  A[README] --> B[GitHub 渲染]
4
```

GitHub 还支持在 Markdown 中创建多种图表，包括 Mermaid、GeoJSON、TopoJSON 和 STL 3D 模型等。Mermaid 在 GitHub 上适合 README、Issue、Pull Request、Wiki 文档。

注意：

• GitHub 支持不等于所有 Markdown 平台都支持。
• 图表渲染由 GitHub 控制，主题和安全能力可能与本地不同。
• 若图表对博客展示非常重要，建议导出 SVG 作为兜底。

21.2 Jekyll / GitHub Pages#

Jekyll 默认不会自动渲染 Mermaid。常见方案：

1. 在布局模板中引入 Mermaid JS。
2. 使用 Jekyll 插件处理 Mermaid 代码块。
3. 构建前用 Mermaid CLI 导出 SVG/PNG。

如果你的博客部署在 GitHub Pages，需要注意：

• GitHub 仓库页面能渲染 Mermaid，不代表 GitHub Pages 生成的网站能自动渲染 Mermaid。
• GitHub Pages 的 Jekyll 插件白名单有限，部分插件不能直接使用。
• 最稳妥方案是用 CLI 预渲染为 SVG，然后在 Markdown 中引用图片。

一个简单 HTML 引入方式可放在 Jekyll 布局中：

1
<script type="module">
2
  import mermaid from "https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs";
3
  mermaid.initialize({ startOnLoad: true, theme: "neutral" });
4
</script>

但这要求页面上的 Mermaid 代码块能被正确保留为 Mermaid 可识别的 DOM 结构。不同主题和 Markdown 渲染器可能需要额外适配。

21.3 VS Code#

常见方式：

• 使用 Markdown Preview Mermaid Support 插件。
• 使用 Mermaid Markdown Syntax Highlighting 插件。
• 使用 Mermaid Live Editor 验证后再复制到文档。

VS Code 预览和最终博客渲染不一定完全一致。关键文档建议在目标平台验证。

23.1 流程图#

23.2 时序图#

23.3 架构图#

24.1 命名规范#

推荐：

不推荐：

说明：

• 小图用 A/B/C 可以接受。
• 中大型图建议使用有意义的 ID。
• 节点 ID 尽量使用英文、数字、下划线，节点显示文本可以用中文。

24.2 文案规范#

建议：

• 节点文本保持短句。
• 判断节点使用疑问句。
• 边文本使用条件或动作。
• 一个图只表达一个主题。
• 节点超过 15 个时考虑拆图。

24.3 结构规范#

建议顺序：

1
1. 图类型声明
2
2. 全局配置
3
3. 节点声明
4
4. 子图分组
5
5. 关系连线
6
6. 样式声明

复杂图可以先声明节点，再统一声明关系，这样更容易维护。

25.1 classDef 和 class#

25.2 style 单独设置节点#

建议：

• 只给关键节点加样式，不要每个节点都手动设置。
• 团队文档中应统一主题，不要每张图一套颜色。
• 样式用于辅助理解，不要依赖颜色传递唯一信息。

26.1 平台不渲染 Mermaid#

现象：

• Markdown 中显示代码块，没有图。

原因：

• 当前平台不支持 Mermaid。
• Mermaid 插件未启用。
• 代码块语言标识写错。
• Jekyll 或 Markdown 渲染器转义了内容。

处理：

• 确认代码块是 ```mermaid。
• 在 Mermaid Live Editor 验证语法。
• 对博客用 Mermaid CLI 导出 SVG 作为图片。
• 对 Jekyll 检查布局是否引入 Mermaid JS。

26.2 中文、空格、特殊字符导致解析失败#

建议：

• 节点 ID 使用英文。
• 中文放在节点显示文本中。
• 特殊字符使用引号包裹。
• 避免在 ID 中使用括号、斜杠、冒号等符号。

推荐：

26.3 节点文本太长#

问题：

• 图变得很宽。
• 自动布局不可控。
• 移动端阅读困难。

处理：

• 拆成多个节点。
• 使用短标签，详细说明写在图下方正文。
• 复杂图拆为多张图。

26.4 图太复杂#

判断标准：

• 节点超过 15 到 20 个。
• 箭头交叉严重。
• 一个图同时表达流程、状态、数据结构和架构。

处理：

• 按层级拆图。
• 按场景拆图。
• 用 C4 分层表达架构。
• 先画总览，再画局部细节。

26.5 GitHub 能显示，博客不能显示#

这是常见误解。GitHub 仓库页面支持 Mermaid，不代表 GitHub Pages 或 Jekyll 主题自动支持 Mermaid。

解决思路：

• 方案 A：在 Jekyll 布局中引入 Mermaid JS。
• 方案 B：使用支持 Mermaid 的 Markdown 渲染插件。
• 方案 C：用 CLI 预渲染 SVG/PNG。

如果你希望笔记长期稳定展示，方案 C 最可靠。

26.6 主题在不同平台不一致#

原因：

• GitHub、VS Code、本地网页、CLI 使用的 Mermaid 版本可能不同。
• 平台可能覆盖主题变量。
• 暗色模式下颜色表现不同。

处理：

• 使用 theme: "neutral" 或导出 SVG。
• 避免依赖平台默认颜色表达含义。
• 重要文档在目标平台截图或预览确认。

26.7 安全策略导致链接或 HTML 不生效#

Mermaid 支持一定程度的链接、点击、HTML 标签，但平台可能禁用。

建议：

• 公共文档里不要依赖 Mermaid 的点击事件。
• 链接和详细说明写在图外 Markdown 正文。
• 对用户可编辑内容使用严格安全等级。

29.1 API 调用时序图模板#

29.2 服务架构流程图模板#

29.3 状态机模板#

29.4 数据库 ER 模板#

31.1 建立图表规范#

建议团队约定：

• 常用图类型。
• 节点命名规则。
• 图表主题。
• 是否允许 HTML。
• 复杂图拆分标准。
• Mermaid CLI 版本。
• 导出图片存放目录。

31.2 把 Mermaid 放入文档流程#

推荐流程：

31.3 版本固定#

如果使用 CLI 生成图片，建议在项目中固定版本：

1
npm install --save-dev @mermaid-js/mermaid-cli@11.15.0

然后在 package.json 中写脚本：

1
{
2
  "scripts": {
3
    "diagram:build": "mmdc -i docs/diagram.mmd -o docs/diagram.svg"
4
  }
5
}

固定版本的好处：

• 本地和 CI 输出一致。
• 避免 Mermaid 新版本布局变化导致文档 diff。
• 便于回溯构建问题。

32.1 图类型速查#

1
flowchart TD
2
sequenceDiagram
3
classDiagram
4
stateDiagram-v2
5
erDiagram
6
gantt
7
pie
8
journey
9
gitGraph
10
mindmap
11
timeline
12
quadrantChart
13
architecture-beta
14
C4Context

32.2 Flowchart 速查#

1
A[矩形]
2
A(圆角)
3
A((圆形))
4
A{判断}
5
A[/输入输出/]
6
A[(数据库)]
7
A --> B
8
A -- 文案 --> B
9
A -.-> B
10
A ==> B
11
subgraph Name
12
  A --> B
13
end

32.3 Sequence 速查#

1
participant A as 客户端
2
A->>B: 请求
3
B-->>A: 响应
4
activate B
5
deactivate B
6
alt 条件
7
else 其他条件
8
end
9
loop 循环
10
end
11
opt 可选
12
end
13
par 并行
14
and 另一路并行
15
end

32.4 Class 速查#

1
class User {
2
  +String id
3
  -String password
4
  +login()
5
}
6
Animal <|-- Dog
7
Interface <|.. Impl
8
Whole *-- Part
9
Group o-- Member
10
A --> B
11
A ..> B