# Mermaid 技术介绍文档

1. 概述

1.1 什么是 Mermaid？

Mermaid 是一个基于 JavaScript 的开源图表绘制工具，它允许用户通过简单的文本代码来生成和修改图表。类似于 Markdown 通过简化语法来格式化文本，Mermaid 通过简化语法来绘制图表，解决了"文档即代码"在图表领域的缺失问题。

1.2 核心价值

降低绘图门槛：无需学习复杂的图形设计软件（如 Visio），只需编写文本即可生成专业图表。
版本控制友好：图表定义以文本形式存储，可纳入 Git 版本管理，便于追踪变更历史和多人协作。
动态渲染：图表在支持的环境中实时渲染，修改代码即可即时更新图表，无需手动重绘。
文档一体化：能与 Markdown 文档无缝集成，保持代码与图表的同步更新，避免文档滞后。

2. 支持的图表类型

Mermaid 支持广泛的图表类型，几乎涵盖了软件开发生命周期中的所有可视化需求：

图表类型	关键字	典型应用场景
流程图	`graph`	算法逻辑、业务流程、系统架构概览
序列图	`sequenceDiagram`	API 交互、消息队列流转、微服务调用链
类图	`classDiagram`	数据库模型设计、面向对象类结构设计
状态图	`stateDiagram-v2`	对象生命周期、状态机流转
实体关系图	`erDiagram`	数据库表结构关系设计
用户旅程图	`journey`	用户体验分析、产品流程梳理
甘特图	`gantt`	项目进度管理、里程碑规划
饼图	`pie`	数据占比分析
Git 图	`gitGraph`	Git 分支管理与提交记录可视化
思维导图	`mindmap`	头脑风暴、知识体系梳理
四象限图	`quadrantChart`	产品优先级评估、风险分析
时间线图	`timeline`	项目历程、历史事件、发布记录

图表示例

以下是 10 种主要图表类型的示例代码：

1. 流程图

是
否
开始
是否登录?
显示主页
跳转登录页
结束

2. 序列图

系统用户系统用户发送请求处理数据返回响应

3. 类图

Animal
+String name
+int age
+eat()
+sleep()
Duck
+quack()
+swim()
Fish
-int finCount
+swim()

4. 状态图

支付成功
确认发货
用户签收
未支付
已支付
已发货
已签收

5. 实体关系图

places
contains
CUSTOMER
string
name
string
email
int
id
PK
ORDER
int
id
PK
date
created
string
status
LINE-ITEM

6. 用户旅程图

用户浏览商品浏览商品用户浏览列表浏览列表用户查看详情查看详情下单下单用户加入购物车加入购物车用户支付订单支付订单收货收货用户等待收货等待收货用户确认收货确认收货用户购物旅程

7. 甘特图

2024-01-07 2024-01-14 2024-01-21 2024-01-28 2024-02-04 2024-02-11 需求分析 UI设计后端开发前端开发系统测试设计开发测试项目开发计划

8. 饼图

45% 25% 15% 15% 编程语言使用率 JavaScript Python Java 其他

9. Git 图

main develop 初始提交功能A 合并功能A 修复bug

10. 思维导图

Mermaid图表
流程图
基本流程图
时序流程图
序列图
参与者
消息
激活框
类图
类定义
关系
方法属性

3. 工作流与工具集成

3.1 在线编辑

对于快速验证和生成图片，推荐使用官方在线编辑器：

Mermaid Live Editor : https://mermaid.live/
- 左侧编写代码，右侧实时预览
- 支持 SVG/PNG 导出，支持获取链接分享

3.2 本地开发环境

开发者可以将 Mermaid 集成到应用或 Node.js 脚本中：

NPM 包安装:

bash 复制代码

npm install mermaid

Web 集成:

html 复制代码

<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
  <script>
    mermaid.initialize({ startOnLoad: true });
  </script>
</head>
<body>
  <div class="mermaid">
    graph TD
      A[开始] --> B[结束]
  </div>
</body>
</html>

3.3 编辑器插件推荐

VS Code: Markdown Preview Mermaid Support
Obsidian: 原生支持 Mermaid
Typora: 原生支持 Mermaid
IntelliJ IDEA: Mermaid 插件
Notion: 通过代码块支持 Mermaid

4. 最佳实践

4.1 图表选择建议

流程图：用于展示"怎么做"，适合业务流程、算法逻辑
序列图：用于展示"谁在什么时候做了什么"，适合交互时序
类图/ER图：用于展示"静态的数据结构"，适合系统设计
甘特图：用于展示"时间上的安排"，适合项目管理
状态图：用于展示"状态如何转换"，适合状态机设计

4.2 可维护性原则

保持简洁：单图节点不宜超过 20 个，复杂流程可拆分子图
命名规范：节点 ID 应简洁，节点文本应清晰描述业务含义
样式统一 ：使用 classDef 统一管理样式，便于主题维护
版本控制：将 Mermaid 代码纳入版本管理，进行 Code Review
注释说明：在复杂图表中添加必要的注释说明

示例：使用样式类
是
否
开始
条件判断?
处理流程
结束

4.3 注意事项

兼容性：部分旧版 Markdown 查看器可能不支持 Mermaid
安全性：渲染不可信代码源时需谨慎
性能：超大型图表可能影响渲染性能
样式定制：深度定制需要了解 CSS 样式覆盖

5. 学习资源

5.1 官方资源

官方文档 : https://mermaid.js.org/
GitHub 仓库 : https://github.com/mermaid-js/mermaid
在线编辑器 : https://mermaid.live/

5.2 社区资源

Stack Overflow: mermaid 标签
Discord 社区: Mermaid 官方 Discord 服务器
中文教程: 国内技术博客的相关教程

5.3 进阶学习

主题定制：学习如何配置和自定义图表主题
API 集成：了解如何在项目中集成 Mermaid API
插件开发：探索如何为 Mermaid 开发插件扩展

6. 总结

Mermaid 作为"文档即代码"理念在图表领域的重要实践，通过简洁的文本语法降低了图表绘制的门槛，提高了文档的可维护性和协作效率。无论是个人笔记、技术文档还是团队协作，Mermaid 都能提供强大而灵活的图表支持。

使用建议：

从简单的流程图开始，逐步学习其他图表类型
结合具体项目需求，选择合适的图表类型
利用版本控制管理图表代码，确保文档同步
参与社区交流，分享最佳实践和技巧

随着 Mermaid 生态的不断完善，它在技术文档、项目管理和知识分享等场景中的应用将越来越广泛。