认识 Mermaid：让文档自己画图的「文本即图形」引擎

Mermaid是一个基于文本生成图表的工具，通过简单的文本语法即可自动渲染流程图、时序图、甘特图等。它支持多种图形类型，包括流程图（定义节点形状和连线样式）、时序图（描述交互流程）、甘特图（规划项目进度）和类图（展示类与关系）。Mermaid语法简洁，可版本控制，无需图形化工具，适合集成到Markdown文档中。其核心优势是低心智负担、可版本化、自动化生成和广泛生态支持（如GitHub、VS Co

aiweker

1359人浏览 · 2025-08-21 21:37:54

aiweker · 2025-08-21 21:37:54 发布

01 认识 Mermaid：让文档自己画图的「文本即图形」引擎

在软件需求、技术方案、会议纪要里，流程图、时序图几乎是标配。传统做法需要打开 Visio、draw.io 或 PowerPoint 手动拖拽，不仅耗时，而且版本管理困难、协作成本高。
Mermaid 把“画图”这件事变成了“写文档”——只要在 Markdown 里写几行类 Markdown 的文本，就能自动渲染出可交互、可搜索、可版本控制的矢量图。它的意义可以概括为：

低心智负担：纯文本，无 UI 操作；
可版本化：图就是代码，diff 清晰可见；
自动化：结合 CI/CD 可以在文档、Wiki、Slide 中自动生成最新图；
生态成熟：GitHub、GitLab、Notion、Obsidian、VS Code 均已原生或插件支持。

02 Mermaid 语法总览

Mermaid 语法由“声明块 + 图类型 + 图描述”三部分构成，最简模板如下：

```mermaid
%% 可选：声明图类型
graph TD        %% TD=Top-Down，可换成 LR/RL/BT
    A[开始] --> B{条件}
    B -->|true| C[处理]
    B -->|false| D[结束]
```

渲染结果：

03 核心功能与实战示例

下面按场景拆分，逐一枚举常用功能，并给出可直接复制运行的代码。

03-1 Flowchart（流程图）

功能点

方向控制（TD/LR/RL/BT）
节点形状（矩形、圆角、圆形、子图、数据库）
连线样式（实线、虚线、箭头、无箭头、加粗）
子图（subgraph）实现嵌套布局

示例：订单状态机

```mermaid
%% 方向：Top-Down
flowchart TD
    %% 节点形状
    S([开始]) --> P[待支付] -->|支付成功| W{库存检查}
    W -->|有货| A[已发货]
    W -->|缺货| C[退款中]
    C --> E([结束])
    A --> E

    %% 子图：展示“已发货”内部流程
    subgraph 物流子流程
        A --> T[拣货] --> D[配送]
    end

    %% 样式
    classDef green fill:#c2e0c6,stroke:#006100
    classDef red   fill:#f2b3b3,stroke:#c5504b
    class A green
    class C red
```

渲染结果：

解读

([ ]) 圆形节点；{ } 菱形判断；[ ] 矩形。
classDef 自定义颜色，配合 class 语句批量着色。
subgraph 关键字创建可折叠区域，便于大型流程分层展示。

03-2 Sequence Diagram（时序图）

功能点

Actor / Participant 声明
同步/异步消息（->, -->>）
激活条（activate、deactivate）
循环（loop）、可选（opt）、并行（par）片段

示例：OAuth2 授权码流程

```mermaid
sequenceDiagram
    participant U as 用户浏览器
    participant A as 前端 App
    participant S as 授权服务器
    participant R as 资源服务器

    U->>A: 点击登录
    A->>U: 302 重定向到 /authorize
    U->>S: 登录并同意授权
    S->>U: 302 返回 code
    U->>A: 携带 code 回前端
    A->>S: POST /token code+secret
    activate S
    S-->>A: 返回 access_token
    deactivate S

    A->>R: GET /userinfo
    activate R
    R-->>A: 返回用户信息
    deactivate R
```

渲染结果：

解读

participant X as 别名 解决中文或长名问题。
activate/deactivate 生成激活条，突出耗时操作。
-->> 虚线箭头表示异步返回。

03-3 Gantt（甘特图）

功能点

任务、里程碑、章节分组
日期格式、工作日历
关键路径高亮

示例：两周 Sprint 计划

```mermaid
gantt
    title Sprint 25 甘特图
    dateFormat YYYY-MM-DD
    excludes weekends
    section 需求
    需求澄清  :a1, 2025-08-20, 2d
    section 开发
    接口设计  :dev1, after a1, 1d
    前端开发  :dev2, after dev1, 3d
    后端开发  :dev3, after dev1, 3d
    section 测试
    联调      :t1, after dev2, 1d
    回归测试  :t2, after t1, 1d
    上线      :m1, milestone, after t2, 0d
```

渲染结果：

gantt
    title Sprint 25 甘特图
    dateFormat YYYY-MM-DD
    excludes weekends
    section 需求
    需求澄清  :a1, 2025-08-20, 2d
    section 开发
    接口设计  :dev1, after a1, 1d
    前端开发  :dev2, after dev1, 3d
    后端开发  :dev3, after dev1, 3d
    section 测试
    联调      :t1, after dev2, 1d
    回归测试  :t2, after t1, 1d
    上线      :m1, milestone, after t2, 0d

解读

after 任务名 建立依赖，自动计算开始时间。
excludes weekends 排除周末，甘特条会自动跳过。
milestone 零耗时节点，常用于发布节点。

03-4 Class Diagram（类图）

功能点

类、接口、枚举、包
可见性（+ public、- private、# protected）
关系：继承（<|–）、组合（*–）、聚合（o–）、关联（–>）

示例：电商核心域模型

```mermaid
classDiagram
    class Customer {
        -String id
        -String name
        +register()
    }

    class Order {
        -String orderNo
        -BigDecimal amount
        +pay()
    }

    class Product {
        -String sku
        -int stock
        +reduceStock()
    }

    class OrderItem {
        -int quantity
    }

    Customer "1" --> "*" Order : places
    Order "1" *-- "*" OrderItem : contains
    OrderItem "*" --> "1" Product : refers
```

渲染结果：

解读

"1" --> "*" 表示一对多关联，语义与 UML 一致。
*-- 实心菱形代表强聚合（整体-部分生命周期一致）。

03-5 State Diagram（状态机）

功能点

状态、转移、开始/结束节点
并发状态（fork/join）

示例：工单状态

```mermaid
stateDiagram-v2
    [*] --> New
    New --> Assigned : 分派
    Assigned --> Processing : 开始处理
    Processing --> Resolved : 修复
    Resolved --> Closed : 客户确认
    Resolved --> Reopened : 未解决
    Reopened --> Processing
    Closed --> [*]
```

渲染结果：

03-6 Pie Chart（饼图）

```mermaid
pie title 本月服务器错误分布
    "5xx" : 42
    "4xx" : 28
    "Timeout" : 15
    "Network" : 9
    "Other" : 6
```

03-7 Requirement Diagram（需求追踪）

需求图可追溯到测试用例，适合 MBSE（基于模型的系统工程）。

```mermaid
requirementDiagram
    requirement req {
        id: 1
        text: 用户登录时间 ≤ 2 秒
        risk: high
        verifymethod: test
    }
    test_case tc {
        id: TC-01
        title: 登录性能测试
    }
    req - traces -> tc
```

04 进阶技巧

主题与自定义样式：
Mermaid 内置 7 套主题（default、dark、forest、neutral、base、darkMode、base），也支持覆盖 CSS 变量。
```
%%{init: {'theme':'dark'}}%%
```
CLI & CI 集成：
安装 @mermaid-js/mermaid-cli，可在 GitHub Actions 中把 .mmd 文件批量转成 .svg 或 .png，并上传到文档站点。
VS Code 插件：
插件 “Markdown Preview Mermaid Support” 支持实时预览，断点调试语法。
PlantUML 迁移：
用 mermaid-to-plantuml 反向转换，或利用 mermaid-zenuml 输出更符合中文习惯的时序图。

05 总结

Mermaid 把“图”纳入源码管理，极大降低了维护成本。
支持 10+ 种图类型，覆盖需求、架构、排期、运维指标等全链路场景。
语法简洁，生态工具链完备，从本地 Markdown 预览到线上自动化文档，全流程无缝。
对于团队写作、Code Review、技术博客，Mermaid 都是“写一次，到处渲染”的利器。

下次写文档时，不妨先敲几行 Mermaid，让图“自己长出来”。Happy diagramming!

2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

年薪百万的AI架构师都在用的数据安全智能体设计模式

当企业还在靠“防火墙+人工分析师”被动堵漏洞时，年薪百万的AI架构师已经在用数据安全智能体重构安全体系——它像“会思考的智能保安”：能主动感知异常、理解威胁意图、自动采取行动，甚至从经验中学习优化。本文将拆解这套“年薪百万级”设计模式：从核心组件的生活化比喻，到AI算法与安全规则的融合逻辑，再到电商/金融场景的实战落地，最后展望未来多智能体协作、大模型整合的趋势。无论你是AI工程师、安全架构师还是

2048 AI社区

基于C++的HTTP WebServer实现 -- Sourcetrail使用说明（CPP项目）

本文介绍了如何使用Sourcetrail工具分析C++项目代码结构。Sourcetrail是一款跨平台源代码可视化工具，通过解析编译数据库生成交互式关系图，帮助开发者理解大型项目结构。文章详细说明了安装过程、创建项目步骤（包括生成compile_commands.json文件）、以及如何使用搜索框、CustomTrail等功能来查看类图、函数调用关系等。特别针对C++项目可能遇到的编译问题提供了解

2048 AI社区

揭秘全解：提示工程架构师提示工程文档规范指南揭秘全解

提示工程文档是记录提示全生命周期（设计→测试→迭代→协作）的结构化文档沉淀知识：把“个人经验”变成“团队资产”；统一认知：让技术、业务、运营对“AI能力”达成共识；可追溯性：迭代时能快速定位“为什么变”“变了什么”；降低风险：避免因“口口相传”导致的错误。这是文档的“核心”，要写清楚“提示的目标、输入输出、规则、示例”，让所有人都能看懂“这个提示是做什么的”。输入：明确AI需要的“信息项”（必填/

2048 AI社区

所有评论(0)

查看更多评论

aiweker

@dnnyyq

已为社区贡献7条内容