Mermaid 图表语法：Markdown 与 Obsidian 实用示例

Mermaid 图表是通过 Mermaid JS 库从纯文本代码生成的可视化图形。该开源项目由 Knut Sveidqvist 于 2014 年前后创建，现已成为软件文档中基于文本绘图的标准。到 2026 年，包括 GitHub、GitLab 和主流文档工具在内的大多数平台都已经原生支持渲染 Mermaid 语法。

本指南将详细介绍 Mermaid 语法、核心图表类型、Markdown 与 Obsidian 中的渲染方式、导出选项以及常见问题的排查。

基础语法示例如下：

graph TD
    A[Start] --> B[Process]
    B --> C[Complete]

“图表即代码”（diagrams as code）的方法通过版本控制极大地提升了可维护性，并简化了工程团队之间的协作。后续章节将介绍常见图表类型、分步创建方法以及如何将图表导出为静态图片供相关利益方查看。

Mermaid 语法速查表

图表类型	起始关键字	典型应用场景
流程图	flowchart TD 或 flowchart LR	业务流程与决策路径
时序图 / 顺序图	sequenceDiagram	请求响应流与服务间交互
实体关系图 (ER 图)	erDiagram	数据库实体及其关联 relationship
状态图	stateDiagram-v2	状态流转与生命周期变化
甘特图	gantt	项目里程碑与时间进度计划
类图	classDiagram	领域模型与对象模型设计

每个 Mermaid 代码块都需要一个起始关键字。节点 ID 建议保持简短稳定；显示的文本标签可以包含更长且易读的说明。

什么是 Mermaid 图表？为什么要使用它？

Mermaid 图表是由 JavaScript 库 Mermaid 解析轻量级文本语法后自动生成的。您无需使用拖拽式界面，只需编写 Mermaid 图表代码，该库即可将其转换为 SVG 矢量图形。

Mermaid 代码如何转化为可视化图形：

• graph TD; A –> B; 渲染为自顶向下的流程图

• sequenceDiagram 代码块会生成展示消息流转的时序图

• erDiagram 定义将绘制出数据库实体关系图

文本绘图的核心优势：

• 任何人均可编辑的纯文本，人类可读性强

• 对 Git 非常友好，能够精准显示更改差异（diff）

• 简化 Pull Request 中的代码审查流程

• 无需管理专有的图表文件格式

2026 年的具体应用场景：

• 使用时序图记录微服务身份验证流程

• 绘制从代码提交到生产部署的 CI/CD 流水线

• 使用甘特图规划 2026 年第二季度的产品发布里程碑

Mermaid 图表能够无缝融入基于 Markdown 的文档、内部 Wiki 和开发者门户，从而简化整个组织的文档管理流程。

核心 Mermaid 图表类型

Mermaid 支持丰富的图表类型。本节将提供最实用图表的实用概述，而非事无巨细的参考手册。

主要图表类型：

类型	关键字	最适合用于
流程图	graph TD / flowchart LR	流程图、决策树
时序图	sequenceDiagram	API 调用、服务间交互
类图	classDiagram	对象模型、领域设计
状态图	stateDiagram-v2	生命周期状态、工作流
实体关系图 (ER 图)	erDiagram	数据库 Schema 设计
用户旅程图	journey	客户体验映射
甘特图	gantt	项目时间线、路线图
饼图	pie	比例数据可视化
Git 分支图	gitGraph	分支策略演示

实际应用示例：

• 前端 → API 网关 → 支付服务 API 流程的时序图

• 包含依赖关系的 2026 Q2 功能路线图甘特图

• 订单生命周期状态图：待处理 → 已支付 → 已发货 → 已送达

流程图、时序图、ER 图和状态图是软件团队最常用的类型。而产品和运营团队则倾向于使用用户旅程图、甘特图和饼图来展示客户体验和业务流程。

sequenceDiagram
    participant User
    participant API
    User->>API: POST /login
    API-->>User: 200 OK + Token

如何创建 Mermaid 图表

快速创建流程图始于理解其基本结构。您可以使用任何文本编辑器搭配 Mermaid 语法来创建图表。

分步操作流程：

1. 以图表关键字开头（如 graph TD、sequenceDiagram、gantt）

2. 使用 ID 和文本标签定义节点或参与者

3. 使用箭头或关联线连接各元素

4. 根据需要添加标签和分组（subgraph）

以下是一个完整可用的用户登录流程图示例：

graph TD
    U[User] --> LP[Login Page]
    LP --> AS[Auth Service]
    AS --> DB[(User Database)]
    AS -->|Success| DASH[Dashboard]
    AS -->|Failure| ERR[Error Page]

箭头类型与文本标签：

• –> 创建标准有向箭头

• –>|label| 在连接线上添加条件文本

• — 绘制无箭头的直线

• -.-> 生成虚线箭头，表示间接关系

Mermaid 会自动使用 ELK 布局算法对节点进行排版。您只需专注于逻辑结构和命名，无需手动调整位置——没有任何额外的布局代码需要编写。

2026 年可以在哪些平台使用 Mermaid 图表

如今，大部分主流平台都原生或通过扩展插件支持了 Mermaid，让您可以随时开始绘图。

主要使用环境：

• GitHub 与 GitLab：在 README.md、文档、Issue 和 Wiki 中提供原生渲染

• 静态网站生成器：借助插件在 Docusaurus、MkDocs 和 Sphinx 中渲染

• 内部开发者门户：Backstage 和自定义 React 应用

• 笔记工具：Notion 和 Obsidian 内置支持 Mermaid 图表

Visual Studio Code 和 JetBrains IDE 通过插件支持实时预览，让您在边输入边预览图表。这有助于在提交代码前发现语法错误。

部分平台（如 Confluence Cloud）需要安装应用市场插件。团队通常将图表源码存储在代码仓库中，同时导出图片以便非技术人员查看。

在不同平台上渲染 Mermaid 图表

渲染是将 Mermaid 文本转化为 SVG/HTML 视觉图形的过程。具体渲染方式取决于目标平台的整合程度。

通用模式：将 Mermaid 代码放入标注了 mermaid 语言标识符的代码块中。GitHub、GitLab 和静态文档生成器在浏览器中加载时会自动将其渲染为图形。

对于本地开发，编辑器扩展插件提供了分屏实时预览。在基于 Sphinx 的文档中，可通过 sphinxcontrib-mermaid 等扩展在构建过程中自动生成图表。

在 Markdown 文件中渲染 Mermaid

要在 Markdown 中渲染 Mermaid：

1. 使用三个反引号打开代码块

2. 指定 mermaid 作为语言标识符

3. 在内部添加您的图表定义

4. 使用三个反引号关闭代码块

```mermaid
flowchart LR
    A[Step 1] -->|Process| B[Step 2]
    B -->|Complete| C[Step 3]
```

• GitHub、GitLab 和现代文档网站均原生支持此模式

• 在合并到主分支之前，请先在预览环境中测试渲染效果

• Mermaid 图表的默认主题适用于绝大多数技术文档

在 Obsidian 中渲染 Mermaid

Obsidian 能够在阅读视图（Reading View）和实时预览（Live Preview）中直接渲染 mermaid 代码块。Obsidian 已内置 Mermaid 支持，因此基础图表无需安装任何社区插件。

如果图表无法正常渲染：

1. 确认起始代码块标记准确无误（即 ```mermaid）。
2. 检查第一行是否为有效的图表关键字（如 flowchart LR）。
3. 如果标签包含特殊标点，请使用双引号包裹，例如 A["Review: blocked?"]。
4. 将图表简化为两个节点，然后逐步添加行，直至于找出引发语法的错误。
5. 确认您使用的 Obsidian 版本是否支持所粘贴的新版 Mermaid 语法。

了解更多 Obsidian 专属的 Markdown 扩展语法，请查阅 Obsidian 基础文本格式速查表。

在 IDE 和本地工具中渲染 Mermaid

Visual Studio Code 的 Mermaid 插件支持边写边预览。多种扩展还提供了语法高亮以及复杂图表的自动修复建议。

JetBrains 系列 IDE 同样通过插件提供类似功能，通常包括错误提示和导出选项。某些工具中的图表修复按钮可以自动解决常见的语法问题。

本地预览有助于在推送到 Git 仓库前发现错误。建议在团队的开发环境配置文档中标准化扩展插件集。

导出与共享 Mermaid 图表

虽然基于代码的编辑方式非常适合开发者，但管理层与相关利益方往往更喜欢将静态图片用于 Microsoft PowerPoint 演示文稿和汇报。

常见导出格式：

• PNG：适合通过即时通讯工具快速分享

• SVG：适用于演示文稿的高质量可缩放矢量图

• PDF：可打印的文档包

不同工具的导出流程有所不同。某些工具内置导出按钮，而某些情况则需要使用 Mermaid Chart 编辑器或在线工具（如 Mermaid Live Editor）。命令行工具还可以在 CI/CD 流程中批量将多个图表文件转换为图片。

请务必保留原始 Mermaid 代码文件，以便日后随时修改图表。

将 Mermaid 图表转换为图片格式

在线编辑器的简易工作流：

1. 在浏览器中打开 Mermaid Live Editor

2. 粘贴您的 Mermaid 代码或使用示例模板

3. 调整 Mermaid 图表的样式设置

4. 根据需要配置主题（提供深色与浅色模式选项）

5. 点击“Download SVG”或“Download PNG”

确保导出的图表使用符合品牌规范的字体和颜色。GitHub 的截屏会变成位图且放大后可能失真——在演示文稿中请优先使用 SVG 导出格式。

Mermaid 图表的最佳实践与局限性

Mermaid 功能强大，但在合理的范围与清晰的结构下才能发挥最佳作用。

建议：

• 每个图表聚焦于单一核心概念

• 使用具备描述性的节点标签与统一的命名规范

• 使用子图（subgraph）代码块对相关步骤进行分组

• 将复杂的系统拆分为多个图表文件，而不是塞入一个庞大的绘图框架中

需要注意的局限性：

• 过于庞大密集的系统很难完全用代码维护

• 布局控制是近似的——无法做到像素级的精确定位

• 样式定制不如传统绘图软件或白板工具灵活

• 不适合用于概念性视觉创作或 UI 原型设计

在架构概览与工作流梳理中推荐使用 Mermaid。当需要像素级排版或复杂的网络拓扑图时，建议切换到专业绘图工具。在某些特定场景下，可视化图表编辑器仍然不可或缺。

快速上手 Mermaid 图表

新用户行动清单：

1. 选择一种图表类型（通常从简单流程图开始）

2. 安装支持可视化编辑或 AI 助手功能的扩展，或打开 Mermaid Live Editor

3. 绘制您当前项目中的一个真实流程（例如 2026 年的部署流水线）

4. 在学习语法模式的过程中不断迭代和扩展图表

核心资源：

• 官方 Mermaid 文档：获取完整的语法参考手册

• Mermaid Live Editor：体验内置 AI 生成功能的在线实验场

• VS Code 扩展：提供丰富的代码片段与模板支持

• 考虑在团队协作平台上配置基础账号以解锁团队功能

在工程手册中添加“图表规范”章节，明确命名约定、推荐图表类型和图表权限。许多团队发现，自然语言描述结合内置的 AI 聊天工具，能够让任何技术背景的成员快速学会创建图表。

采用 Mermaid 图表能将文档管理融入与源代码相同的审查与自动化流程中。无论您是记录模型流水线的机器学习工程师，还是梳理流程的项目管理人员，Mermaid 都能为您的团队带来版本控制化的视觉图表。今天就从绘制第一张图表开始吧。