news 2026/1/3 6:41:48

Mermaid完全指南：从基础到高级的图表语法详解

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
Mermaid完全指南：从基础到高级的图表语法详解

Mermaid完全指南：从基础到高级的图表语法详解

前言：为什么选择Mermaid？

在技术文档、项目说明或技术博客中，图表是传达复杂信息的利器。然而，传统的图表绘制工具往往存在以下痛点：

  • 依赖图形界面，难以版本控制
  • 协作困难，修改繁琐
  • 与文档分离，维护成本高

Mermaid的出现完美解决了这些问题。作为一个基于JavaScript的图表绘制工具，它使用纯文本描述图表，让图表可以像代码一样被版本控制、协作编辑和自动化生成。

一、Mermaid核心特性

1.1 基本优势

✅ 纯文本编写，易于版本控制 ✅ 丰富的图表类型支持 ✅ 高度可定制化 ✅ 开源免费，社区活跃 ✅ 与Markdown完美集成

1.2 支持的主要图表类型

  • 流程图(Flowchart)
  • 时序图(Sequence Diagram)
  • 类图(Class Diagram)
  • 状态图(State Diagram)
  • 实体关系图(ER Diagram)
  • 甘特图(Gantt)
  • 饼图(Pie Chart)
  • 象限图(Quadrant Chart)
  • 需求图(Requirement Diagram)
  • Git图(Git Graph)

二、流程图详解

2.1 基本语法

是
否
开始
判断条件
执行操作1
执行操作2
结束
graph TD A[开始] --> B{判断条件} B -->|是| C[执行操作1] B -->|否| D[执行操作2] C --> E[结束] D --> E

语法说明：

  • graph TD：定义从上到下的流程图
  • graph LR：定义从左到右的流程图
  • A[文本]：矩形节点
  • B{文本}：菱形判断节点
  • -->：带箭头连接线
  • -->|文本|：带标签的连接线

2.2 节点类型

方形节点
圆角节点
椭圆形节点
菱形节点
圆形节点
非对称节点
六边形节点
graph LR A[方形节点] B(圆角节点) C([椭圆形节点]) D{菱形节点} E((圆形节点)) F>非对称节点] G{{六边形节点}} A --> B --> C --> D --> E --> F --> G

2.3 子图（Subgraph）

子流程2
子流程1
F
C
G
D
B
E
A
H
结束
graph TB A --> B A --> C subgraph 子流程1 B --> D D --> E end subgraph 子流程2 C --> F F --> G end E --> H G --> H H --> I[结束]

2.4 样式自定义

开始
处理数据
成功
失败
graph LR A[开始] --> B{处理数据} B --> C[成功] B --> D[失败] style A fill:#f9f,stroke:#333,stroke-width:4px style B fill:#ccf,stroke:#f66,stroke-width:2px,color:#fff style C fill:#9f9,stroke:#333 style D fill:#f99,stroke:#333

三、时序图详解

3.1 基本时序图

用户前端后端数据库提交请求API调用查询数据返回结果JSON响应显示结果用户前端后端数据库
sequenceDiagram participant 用户 participant 前端 participant 后端 participant 数据库 用户->>前端: 提交请求 前端->>后端: API调用 后端->>数据库: 查询数据 数据库-->>后端: 返回结果 后端-->>前端: JSON响应 前端-->>用户: 显示结果

3.2 消息类型

AB实线箭头（同步）虚线箭头（异步）激活B结束激活取消或失败虚线无箭头AB

3.3 循环和条件

客户端服务器登录请求返回token获取数据返回数据页loop[分页获取]错误信息alt[验证成功][验证失败]客户端服务器
sequenceDiagram participant 客户端 participant 服务器 客户端->>服务器: 登录请求 alt 验证成功 服务器-->>客户端: 返回token 客户端->>服务器: 获取数据 loop 分页获取 服务器-->>客户端: 返回数据页 end else 验证失败 服务器-->>客户端: 错误信息 end

3.4 注释和背景色

sequenceDiagram box rgb(200, 220, 255) 用户端 participant 浏览器 participant 移动端 end box rgb(220, 255, 220) 服务器端 participant Web服务器 participant 数据库 end Note left of 浏览器: 用户发起请求 浏览器->>Web服务器: HTTP请求 Note over Web服务器,数据库: 数据处理过程 Web服务器->>数据库: SQL查询 数据库-->>Web服务器: 查询结果 Web服务器-->>浏览器: HTML响应

四、类图详解

4.1 类定义

Animal
+String name
+int age
+eat()
+sleep()
Dog
+String breed
+bark()
Cat
+int lives
+meow()
classDiagram class Animal { +String name +int age +eat() +sleep() } class Dog { +String breed +bark() } class Cat { +int lives +meow() } Animal <|-- Dog Animal <|-- Cat

4.2 关系类型

继承
组合
聚合
关联
依赖
实现
A
B
C
D
E
F
classDiagram class A class B class C class D class E class F A <|-- B : 继承 C *-- D : 组合 E o-- F : 聚合 A --> B : 关联 A ..> B : 依赖 A --|> B : 实现

4.3 类成员可见性

BankAccount
-String accountNumber
#double balance
+String ownerName
~String bankCode
+deposit(amount)
-validateTransaction()
#calculateInterest()
+getBalance()
-logTransaction()
classDiagram class BankAccount { -String accountNumber #double balance +String ownerName ~String bankCode +deposit(amount) -validateTransaction() #calculateInterest() } BankAccount : +getBalance() BankAccount : -logTransaction()

五、状态图详解

5.1 基本状态图

启动命令
暂停命令
恢复命令
停止命令
待机
运行
初始化
处理中
完成
暂停
stateDiagram-v2 [*] --> 待机 待机 --> 运行 : 启动命令 运行 --> 暂停 : 暂停命令 暂停 --> 运行 : 恢复命令 运行 --> 待机 : 停止命令 待机 --> [*] state 运行 { [*] --> 初始化 初始化 --> 处理中 处理中 --> 完成 完成 --> [*] }

5.2 并发状态

系统启动
加载配置
初始化模块
运行中
并发处理
接收请求
处理请求
返回响应
后台任务
定时任务
数据处理
日志记录
系统关闭
stateDiagram-v2 [*] --> 系统启动 state 系统启动 { [*] --> 加载配置 加载配置 --> 初始化模块 初始化模块 --> [*] } state 运行中 { state 并发处理 { 接收请求 --> 处理请求 处理请求 --> 返回响应 } state 后台任务 { 定时任务 --> 数据处理 数据处理 --> 日志记录 } } 系统启动 --> 运行中 运行中 --> 系统关闭 系统关闭 --> [*]

六、甘特图详解

6.1 项目计划

01/0101/0301/0501/0701/0901/1101/1301/1501/1701/1901/2101/2301/2501/2701/2901/3102/0102/0302/05需求分析原型设计UI设计前端开发后端开发集成测试单元测试用户测试设计阶段开发阶段测试阶段项目开发计划
gantt title 项目开发计划 dateFormat YYYY-MM-DD axisFormat %m/%d section 设计阶段 需求分析 :done, des1, 2024-01-01, 7d 原型设计 :active, des2, after des1, 5d UI设计 :des3, after des2, 5d section 开发阶段 后端开发 :dev1, after des3, 10d 前端开发 :dev2, after des2, 12d section 测试阶段 单元测试 :test1, after dev1, 5d 集成测试 :test2, after dev2, 7d 用户测试 :test3, after test2, 5d

6.2 里程碑

2024-01-212024-01-282024-02-042024-02-112024-02-182024-02-252024-03-032024-03-102024-03-172024-03-242024-03-312024-04-072024-04-142024-04-212024-04-28需求确认Alpha版本Beta版本正式发布里程碑产品发布里程碑
gantt title 产品发布里程碑 dateFormat YYYY-MM-DD section 里程碑 需求确认 :milestone, m1, 2024-01-15, 0d Alpha版本 :milestone, m2, 2024-02-28, 0d Beta版本 :milestone, m3, 2024-03-31, 0d 正式发布 :milestone, m4, 2024-04-30, 0d

七、实体关系图

7.1 数据库设计

CUSTOMERstringnamestringemailintcustomerIdPKORDERintorderIdPKdateorderDatestringstatusLINE-ITEMintitemIdPKintquantitydecimalpricePRODUCTintproductIdPKstringproductNamedecimalpriceplacescontainsincludes
erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ LINE-ITEM : contains CUSTOMER { string name string email int customerId PK } ORDER { int orderId PK date orderDate string status } LINE-ITEM { int itemId PK int quantity decimal price } PRODUCT ||--|{ LINE-ITEM : includes PRODUCT { int productId PK string productName decimal price }

八、饼图详解

8.1 数据分布

15%20%35%25%5%开发时间分配需求分析设计编码测试文档
pie title 开发时间分配 "需求分析" : 15 "设计" : 20 "编码" : 35 "测试" : 25 "文档" : 5

8.2 带值显示

65%19%9%4%3%Chrome [65.3]Safari [18.7]Firefox [8.9]Edge [4.1]其他 [3]
pie showData "Chrome" : 65.3 "Safari" : 18.7 "Firefox" : 8.9 "Edge" : 4.1 "其他" : 3.0

九、象限图详解

9.1 技术评估

quadrantChart title 技术栈评估矩阵 x-axis "成熟度低" --> "成熟度高" y-axis "采用率低" --> "采用率高" quadrant-1 "评估" quadrant-2 "采纳" quadrant-3 "规避" quadrant-4 "验证" "React": [0.75, 0.80] "Vue.js": [0.65, 0.70] "Angular": [0.85, 0.60] "Svelte": [0.45, 0.35] "Next.js": [0.70, 0.75]

十、实用技巧和最佳实践

10.1 主题定制

// 自定义主题示例{theme:'base',themeVariables:{primaryColor:'#BB2528',primaryTextColor:'#fff',primaryBorderColor:'#7C0000',lineColor:'#F8B229',secondaryColor:'#006B00',tertiaryColor:'#fff'}}

10.2 与Markdown集成

# 项目文档 ## 系统架构 ```mermaid graph TD 客户端 --> 负载均衡器 负载均衡器 --> Web服务器1 负载均衡器 --> Web服务器2 Web服务器1 --> 数据库 Web服务器2 --> 数据库 ``` ## API调用流程 ```mermaid sequenceDiagram 客户端->>API网关: 请求 API网关->>认证服务: 验证token 认证服务-->>API网关: 验证结果 API网关->>业务服务: 转发请求 业务服务-->>客户端: 返回响应 ```

10.3 性能优化建议

  1. 避免过度复杂：单个图表不要超过50个节点
  2. 使用子图：将相关逻辑分组到子图中
  3. 精简文本：节点文本尽量简洁
  4. 适当使用注释：使用Note添加说明而非长文本节点

10.4 常见问题解决

问题1：图表渲染不完整

解决方案： 1. 检查语法是否正确闭合 2. 确保没有嵌套过深 3. 验证特殊字符是否正确转义

问题2：样式不生效

解决方案： 1. 确认主题文件正确加载 2. 检查CSS选择器是否正确 3. 验证样式优先级

问题3：与编辑器的兼容性问题

解决方案： 1. 使用最新的Mermaid版本 2. 检查编辑器的Mermaid插件版本 3. 考虑使用在线编辑器预览

十一、实际应用案例

11.1 微服务架构图

数据层
基础设施
业务服务
网关层
用户数据库
订单数据库
商品数据库
认证中心
配置中心
消息队列
日志服务
用户服务
订单服务
支付服务
商品服务
API网关
负载均衡
客户端
graph TB subgraph 网关层 GW[API网关] LB[负载均衡] end subgraph 业务服务 A[用户服务] B[订单服务] C[支付服务] D[商品服务] end subgraph 基础设施 E[认证中心] F[配置中心] G[消息队列] H[日志服务] end subgraph 数据层 DB1[(用户数据库)] DB2[(订单数据库)] DB3[(商品数据库)] end 客户端 --> LB --> GW GW --> A GW --> B GW --> C GW --> D A --> E A --> F A --> G A --> H A --> DB1 B --> DB2 D --> DB3 B --> C C --> G

11.2 CI/CD流水线

监控阶段
部署阶段
构建阶段
开发阶段
监控告警
日志分析
用户反馈
迭代优化
预发布环境
集成测试
性能测试
生产部署
构建镜像
安全扫描
镜像推送
代码审查
代码提交
自动化测试
graph LR subgraph 开发阶段 A[代码提交] --> B[代码审查] B --> C[自动化测试] end subgraph 构建阶段 C --> D[构建镜像] D --> E[安全扫描] E --> F[镜像推送] end subgraph 部署阶段 F --> G[预发布环境] G --> H[集成测试] H --> I[性能测试] I --> J[生产部署] end subgraph 监控阶段 J --> K[监控告警] K --> L[日志分析] L --> M[用户反馈] M --> N[迭代优化] end N -.-> A

十二、学习资源推荐

12.1 官方资源

  • 官网: https://mermaid.js.org
  • GitHub: https://github.com/mermaid-js/mermaid
  • 在线编辑器: https://mermaid.live

12.2 实用工具

  1. VS Code插件: Mermaid Preview
  2. Chrome扩展: Mermaid Diagrams
  3. CLI工具: @mermaid-js/mermaid-cli

12.3 进阶学习

  • 官方示例库: 包含所有图表类型的详细示例
  • 社区论坛: 获取帮助和分享经验
  • 贡献指南: 参与Mermaid开发

结语

Mermaid以其简洁的语法和强大的功能，已经成为技术文档中不可或缺的工具。通过本文的详细介绍和实例展示，相信您已经掌握了Mermaid的核心用法。

记住，Mermaid的真正价值在于将复杂的视觉信息转化为可维护的文本。无论是系统架构设计、API接口说明，还是项目计划安排，Mermaid都能帮助您更高效地进行沟通和协作。

开始使用Mermaid，让您的技术文档更加专业和易于维护吧！

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2025/12/31 19:38:55

VSCode Azure QDK 调试失败？（90%开发者都忽略的配置细节）

第一章&#xff1a;VSCode Azure QDK 调试失败&#xff1f;常见现象与根本原因在使用 Visual Studio Code 搭配 Azure Quantum Development Kit&#xff08;QDK&#xff09;进行量子程序开发时&#xff0c;调试失败是开发者常遇到的问题。尽管环境配置看似完整&#xff0c;但运…

作者头像 李华
网站建设 2026/1/1 17:45:58

hsweb-framework Easy-ORM终极指南：企业级数据访问实战手册

hsweb-framework Easy-ORM终极指南&#xff1a;企业级数据访问实战手册 【免费下载链接】hsweb-framework hsweb (haʊs wɛb) 是一个基于spring-boot 2.x开发 ,首个使用全响应式编程的企业级后台管理系统基础项目。 项目地址: https://gitcode.com/gh_mirrors/hs/hsweb-fram…

作者头像 李华
网站建设 2026/1/2 5:18:24

8、量子计算与技术发展：从理论根源到实际应用

量子计算与技术发展：从理论根源到实际应用 一、量子力学的理论根源与基础概念 1.1 量子力学基础的奠定 量子力学的发展在 1900 - 1930 年间经历了创造性的爆发、混乱与冲突。1927 年的第五届索尔维会议将相关辩论推向高潮，此次会议聚焦于量子力学。1930 年，著名科学家保罗…

作者头像 李华
网站建设 2025/12/30 19:48:19

30、RTA API 详解：功能、使用与错误处理

RTA API 详解：功能、使用与错误处理 1. TBLDEF 结构定义 TBLDEF 结构用于定义表的相关信息，其代码如下： int ncol; /** Save file. Path and name of a file which stores* the non-volatile part of the table. The file has* all of the UPDATE statements ne…

作者头像 李华
网站建设 2025/12/31 8:36:46

【量子开发效率提升10倍】：VSCode + Azure QDK标准项目模板深度解读

第一章&#xff1a;量子开发效率提升的背景与意义 随着量子计算从理论探索逐步迈向工程实现&#xff0c;传统软件开发范式在应对量子算法设计、量子线路优化和混合计算架构时暴露出显著瓶颈。量子开发效率的提升已成为推动该技术落地应用的关键因素。 量子开发面临的挑战 量子…

作者头像 李华
网站建设 2026/1/2 13:26:56

ExoPlayer直播优化终极指南：从卡顿诊断到性能提升的完整解决方案

ExoPlayer直播优化终极指南&#xff1a;从卡顿诊断到性能提升的完整解决方案 【免费下载链接】ExoPlayer 项目地址: https://gitcode.com/gh_mirrors/ex/ExoPlayer 想要快速解决ExoPlayer直播卡顿问题&#xff1f;本文为您提供从问题诊断到实战优化的完整ExoPlayer直播…

作者头像 李华