蔡振原1. Mermaid 是什么？为什么你需要这份指南？
Mermaid 是一个基于 JavaScript 的图表和图表生成工具，它允许用户使用简单的文本语法来创建各种图表。我第一次接触 Mermaid 是在 2018 年，当时正在为一个技术文档寻找更好的图表解决方案。传统的绘图工具需要大量的鼠标操作，而 Mermaid 只需要几行代码就能生成专业级的图表，这彻底改变了我的工作流程。
Mermaid 的核心优势在于它的简洁性和可维护性。与传统的 Visio 或 Draw.io 相比，Mermaid 图表可以像代码一样进行版本控制，团队成员可以轻松协作修改。更重要的是，Mermaid 图表可以无缝集成到 Markdown 文档中，这对于技术文档编写者来说简直是福音。
这份指南之所以称为"最全"，是因为它不仅覆盖了基础语法，还深入探讨了自定义样式的各种技巧。市面上大多数教程只停留在基础使用层面，而我们将带你从入门到精通，包括那些官方文档中没有明确说明的实用技巧。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Mermaid 基础语法详解
2.1 流程图（Flowchart）基础
流程图是 Mermaid 中最常用的图表类型之一。让我们从一个最简单的例子开始：
mermaid复制graph TD
A[开始] --> B{条件判断}
B -->|是| C[执行操作1]
B -->|否| D[执行操作2]
C --> E[结束]
D --> E
这段代码定义了一个基本的决策流程。graph TD 表示这是一个从上到下（Top Down）的流程图。Mermaid 支持多种方向定义：
TD或TB：从上到下BT：从下到上LR：从左到右RL：从右到左
节点定义有多种形式：
A[矩形节点]B{菱形决策节点}C(圆角矩形)D((圆形节点))
2.2 时序图（Sequence Diagram）基础
时序图在系统设计时非常有用，可以清晰地展示组件间的交互顺序：
mermaid复制sequenceDiagram
participant 用户
participant 系统
用户->>系统: 登录请求
系统-->>用户: 验证请求
用户->>系统: 提交凭证
系统->>数据库: 查询用户
数据库-->>系统: 返回结果
系统-->>用户: 登录成功
关键语法说明：
participant定义参与者->>表示实线箭头（同步消息）-->>表示虚线箭头（异步消息）- 还可以使用
activate和deactivate显示生命线激活状态
2.3 类图（Class Diagram）基础
类图是面向对象设计的重要工具，Mermaid 的类图语法非常直观：
mermaid复制classDiagram
class 用户 {
+String 用户名
+String 密码
+登录()
+注销()
}
class 角色 {
+String 名称
+List<权限> 权限列表
}
用户 "1" *-- "0..*" 角色 : 拥有
关系表示法：
-->关联*--组合o--聚合-->依赖--|>继承..>实现
2.4 甘特图（Gantt）基础
项目管理中常用的甘特图也能用 Mermaid 轻松创建：
mermaid复制gantt
title 项目计划
dateFormat YYYY-MM-DD
section 设计阶段
需求分析 :a1, 2023-10-01, 7d
原型设计 :after a1, 5d
section 开发阶段
前端开发 :2023-10-15, 10d
后端开发 :2023-10-20, 14d
关键参数：
dateFormat定义日期格式section划分不同阶段- 任务可以指定开始日期和持续时间，或用
after定义相对时间
3. 高级图表类型与技巧
3.1 状态图（State Diagram）
状态图非常适合描述系统或对象的状态变化：
mermaid复制stateDiagram-v2
[*] --> 待机
待机 --> 运行中: 启动命令
运行中 --> 暂停: 暂停命令
暂停 --> 运行中: 继续命令
运行中 --> 待机: 停止命令
暂停 --> 待机: 停止命令
stateDiagram-v2 是 Mermaid 最新的状态图语法，比旧版本更强大。你可以定义：
- 复合状态（嵌套状态）
- 并发状态
- 历史状态
- 状态进入/退出动作
3.2 饼图（Pie Chart）
虽然简单，但饼图在展示比例数据时非常直观：
mermaid复制pie
title 浏览器市场份额
"Chrome" : 65.2
"Safari" : 18.7
"Firefox" : 8.5
"Edge" : 4.3
"其他" : 3.3
注意：数值可以是整数或小数，Mermaid 会自动计算百分比。
3.3 实体关系图（ER Diagram）
数据库设计时常用的ER图：
mermaid复制erDiagram
用户 ||--o{ 订单 : "创建"
用户 {
int id PK
string 姓名
string 邮箱
}
订单 {
int id PK
date 创建时间
decimal 金额
}
关系表示法：
||--o{一对多||--||一对一}o--o{多对多
3.4 用户旅程图（User Journey）
非常适合产品设计，展示用户与系统的交互过程：
mermaid复制journey
title 购物流程
section 浏览商品
用户: 5: 浏览首页
系统: 3: 展示推荐
section 下单
用户: 4: 加入购物车
系统: 2: 库存检查
section 支付
用户: 3: 选择支付方式
系统: 1: 处理支付
每个步骤后面的数字表示相对重要性或时间占比。
4. 自定义样式与主题
4.1 基础样式修改
Mermaid 允许通过 CSS 类来自定义图表样式。以下是一个修改流程图样式的例子：
mermaid复制graph TD
A[开始] --> B{条件判断}
B -->|是| C[执行操作1]
B -->|否| D[执行操作2]
C --> E[结束]
D --> E
classDef default fill:#f9f,stroke:#333,stroke-width:2px;
classDef decision fill:#f96,stroke:#333,stroke-dasharray: 5 5;
classDef process fill:#bbf,stroke:#333;
class A,B,C,D,E process;
class B decision;
classDef 定义样式类，class 将类应用到节点。常用样式属性：
fill填充颜色stroke边框颜色stroke-width边框宽度stroke-dasharray虚线边框color文字颜色
4.2 使用主题
Mermaid 内置了多个主题，可以通过初始化配置来设置：
javascript复制mermaid.initialize({
theme: 'forest',
themeVariables: {
primaryColor: '#ff0000',
edgeLabelBackground: '#ffffff'
}
});
内置主题包括：
default默认主题neutral中性色调dark深色主题forest绿色系主题base基础主题
4.3 高级自定义技巧
对于更复杂的自定义需求，可以直接修改 Mermaid 的渲染配置：
javascript复制mermaid.initialize({
flowchart: {
htmlLabels: false,
curve: 'basis'
},
sequence: {
diagramMarginX: 50,
diagramMarginY: 10,
actorMargin: 50
},
gantt: {
barHeight: 20,
barGap: 4
}
});
这些配置可以控制图表的布局、间距等细节参数。
5. 实战应用与集成
5.1 在 VS Code 中使用 Mermaid
VS Code 是开发者最常用的编辑器之一，通过以下插件可以增强 Mermaid 支持：
- Mermaid Preview - 实时预览 Mermaid 图表
- Mermaid Markdown Syntax Highlighting - 语法高亮
- Markdown All in One - 综合 Markdown 支持
配置建议：
json复制{
"mermaid-editor.preview.autoUpdate": true,
"mermaid-editor.preview.theme": "dark",
"markdown-preview-enhanced.mermaidTheme": "forest"
}
5.2 在网页中集成 Mermaid
在网页中使用 Mermaid 非常简单：
- 引入 Mermaid JS 库：
html复制<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
- 初始化配置：
javascript复制mermaid.initialize({startOnLoad:true});
- 在
<div class="mermaid">中编写图表代码
对于动态内容，可以在内容加载后调用 mermaid.init()。
5.3 与静态网站生成器集成
流行的静态网站生成器都支持 Mermaid：
Hugo：
toml复制[markup]
[markup.goldmark]
[markup.goldmark.renderer]
unsafe = true
[markup.highlight]
codeFences = true
Jekyll：
安装 jekyll-mermaid 插件，在 _config.yml 中添加：
yaml复制plugins:
- jekyll-mermaid
VuePress：
使用 vuepress-plugin-mermaidjs 插件：
javascript复制module.exports = {
plugins: [
['mermaidjs', { theme: 'dark' }]
]
}
6. 性能优化与最佳实践
6.1 大型图表的优化技巧
当图表变得复杂时，可能会遇到性能问题。以下是一些优化建议：
- 分而治之：将大图表拆分为多个小图表，通过超链接关联
- 简化结构：减少不必要的节点和连接
- 延迟渲染：对于初始不可见的图表，在需要时再渲染
- 使用子图：将相关节点分组
mermaid复制graph TD
subgraph 子系统A
A1 --> A2
A2 --> A3
end
subgraph 子系统B
B1 --> B2
B2 --> B3
end
A1 --> B1
6.2 版本控制友好实践
Mermaid 图表作为代码，应该遵循良好的版本控制实践：
- 合理命名：给图表有意义的标题和ID
- 注释说明：在图表代码中添加必要注释
- 模块化：将常用图表片段提取为可复用模块
- 变更记录：在提交信息中说明图表变更
mermaid复制%% 用户登录流程
%% 创建于2023-10-01
%% 最后修改：2023-10-15 增加超时处理
graph TD
用户 -->|输入凭证| 系统
系统 -->|验证| 数据库
数据库 -->|返回| 系统
系统 -->|令牌| 用户
6.3 跨平台兼容性处理
不同平台对 Mermaid 的支持可能有差异，需要注意：
- 语法兼容性：使用最广泛支持的语法特性
- 版本锁定：在团队中统一 Mermaid 版本
- 备用方案：为不支持的环境准备图片备用
- 测试验证：在目标平台上测试图表渲染效果
7. 常见问题与解决方案
7.1 渲染问题排查
当图表无法正常显示时，可以按照以下步骤排查：
- 检查语法：使用 Mermaid Live Editor 验证语法
- 查看控制台：浏览器控制台可能有错误信息
- 版本兼容性：确保使用的语法与版本匹配
- HTML结构：确认图表容器存在且可见
7.2 常见语法错误
以下是一些常见的语法错误及修正方法：
-
缺少方向声明：
mermaid复制graph // 错误，缺少方向 A --> B修正：
mermaid复制graph TD A --> B -
节点定义不一致：
mermaid复制graph TD A[开始] --> B{决策} B --> C(结束 // 括号不匹配修正：
mermaid复制graph TD A[开始] --> B{决策} B --> C(结束) -
特殊字符未转义：
mermaid复制graph TD A["<html>"] --> B // 可能引起问题修正：
mermaid复制graph TD A["<html>"] --> B
7.3 浏览器兼容性问题
Mermaid 在现代浏览器中工作良好，但在旧版本浏览器中可能会遇到问题：
- 不支持 ES6：使用 Mermaid 8.x 或更早版本
- 安全限制：确保从可信源加载 Mermaid
- 内容安全策略：可能需要调整 CSP 设置
- 字体问题：指定通用字体族
8. 进阶技巧与创意应用
8.1 动态交互图表
虽然 Mermaid 主要是静态图表，但可以通过一些技巧实现简单交互：
html复制<div class="mermaid" onclick="updateChart()">
graph TD
A[点击我] --> B[会变化]
</div>
<script>
function updateChart() {
document.querySelector('.mermaid').textContent = `
graph TD
A[已点击] --> B[新状态]
B --> C[完成]
`;
mermaid.init();
}
</script>
8.2 自定义形状与图标
通过 HTML 和 CSS 可以创建自定义节点：
mermaid复制graph TD
A[开始] --> B["<div style='color:red;'>自定义<br>节点</div>"]
B --> C["fa:fa-twitter 社交媒体"]
注意：这种用法在不同平台上的支持可能不一致。
8.3 与其他工具结合
Mermaid 可以与其他工具链结合使用：
- 与 PlantUML 结合：通过转换工具互转
- 与 LaTeX 结合：生成高质量学术图表
- 与 Pandoc 结合：在文档转换时保留图表
- 与 Jupyter 结合：在 Notebook 中显示图表
9. Mermaid 生态系统
9.1 官方工具与资源
- Mermaid Live Editor：在线编辑和预览
- Mermaid CLI：命令行工具
- Mermaid Webpack Loader：Webpack 集成
- Mermaid Filter：Pandoc 过滤器
9.2 社区插件与扩展
- Mermaid-diagrams：VS Code 插件
- Remark-mermaid：Remark 插件
- Mermaid-pdf：PDF 导出工具
- Mermaid-go：Go 语言实现
9.3 学习资源推荐
- 官方文档：最权威的参考
- Mermaid Cheat Sheet：速查表
- Interactive Tutorials：交互式教程
- GitHub 示例库：社区贡献的示例
10. 实际项目案例
10.1 技术文档中的架构图
mermaid复制graph LR
subgraph 客户端
A[Web界面] --> B[API调用]
C[移动App] --> B
end
subgraph 服务端
B --> D[API网关]
D --> E[用户服务]
D --> F[订单服务]
D --> G[支付服务]
E --> H[(用户数据库)]
F --> I[(订单数据库)]
G --> J[(交易数据库)]
end
10.2 项目管理的甘特图
mermaid复制gantt
title 软件开发项目
dateFormat YYYY-MM-DD
section 设计
需求分析 :done, des1, 2023-01-01, 7d
原型设计 :active, des2, after des1, 5d
section 开发
前端开发 : dev1, after des2, 15d
后端开发 : dev2, after des2, 20d
section 测试
单元测试 : test1, after dev1, 10d
集成测试 : test2, after dev2, 10d
10.3 系统状态转换图
mermaid复制stateDiagram-v2
[*] --> 待机
待机 --> 启动中: 开机命令
启动中 --> 运行中: 启动完成
运行中 --> 更新中: 检测到更新
更新中 --> 重启中: 更新完成
重启中 --> 运行中: 重启完成
运行中 --> 待机: 关机命令
更新中 --> 错误: 更新失败
重启中 --> 错误: 重启失败
错误 --> [*]: 手动恢复
11. Mermaid 的局限性与替代方案
11.1 当前版本的局限性
- 复杂布局限制：自动布局有时不够理想
- 样式自定义局限：某些细节难以精确控制
- 交互功能有限：原生不支持复杂交互
- 性能问题：超大型图表可能卡顿
11.2 替代方案比较
| 工具 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| Mermaid | 文本定义，版本控制友好 | 样式控制有限 | 技术文档，简单图表 |
| PlantUML | 功能丰富，支持多种图表 | 需要Java环境 | 复杂系统设计 |
| Draw.io | 可视化编辑，功能强大 | 二进制文件格式 | 需要精细控制的图表 |
| Graphviz | 强大的布局算法 | 学习曲线陡峭 | 需要精确布局的图表 |
11.3 未来发展方向
根据 Mermaid 的路线图，未来版本可能会加入：
- 更强大的布局引擎
- 增强的交互功能
- 更多的图表类型
- 更好的可访问性支持
12. 个人经验与建议
在实际项目中使用 Mermaid 多年，我总结了以下经验：
- 团队标准化：建立统一的图表风格指南
- 渐进式采用：从简单图表开始，逐步应用复杂功能
- 文档注释：在图表代码中添加充分注释
- 版本控制：将图表与相关代码一起管理
- 持续学习：关注 Mermaid 的新特性和最佳实践
对于初学者，我的建议是：
- 从流程图和时序图开始练习
- 使用 Live Editor 快速验证想法
- 参考官方示例学习高级技巧
- 加入社区讨论和贡献
Mermaid 最大的优势在于它的简洁性和可维护性。虽然它可能无法替代专业绘图工具的所有功能，但对于大多数技术文档需求来说，它提供了完美的平衡点。随着不断的更新和发展，Mermaid 正在成为技术沟通中不可或缺的工具。