Mermaid 图表语法全解

· ··· ·
#Mermaid #Markdown #文档写作 #可视化

前言

在技术文档中，「一图胜千言」。Mermaid.js 让我们可以在 Markdown 中直接用文本绘制图表，无需导出图片，保持纯文本的可维护性。

本文集中展示 Mermaid 各主流图表类型的效果。

流程图 (Flowchart / Graph)

最简单的流程图，展示一个 CI/CD 流水线：

graph LR
    A[代码提交] --> B{CI 构建}
    B -->|通过| C[自动化测试]
    B -->|失败| D[通知开发者]
    C --> E{测试结果}
    E -->|通过| F[部署到生产]
    E -->|失败| D
    F --> G[健康检查]

时序图 (Sequence Diagram)

展示前端与后端 API 的交互流程：

sequenceDiagram
    actor U as 用户
    participant F as 前端 SPA
    participant A as API Gateway
    participant S as 后端服务
    participant D as 数据库

    U->>F: 点击登录按钮
    F->>A: POST /api/auth/login
    A->>S: 转发认证请求
    S->>D: 查询用户信息
    D-->>S: 返回用户数据
    S-->>A: JWT Token
    A-->>F: Token + 用户信息
    F-->>U: 跳转到首页

类图 (Class Diagram)

展示一个简单的博客系统数据模型：

classDiagram
    class Post {
        +String title
        +String slug
        +String content
        +Date pubDate
        +String[] tags
        +Boolean draft
        +publish() void
        +archive() void
    }
    class Author {
        +String name
        +String email
        +String avatar
        +createPost() Post
        +editPost() Post
    }
    class Collection {
        +String name
        +String description
        +Post[] posts
        +getLatestPosts() Post[]
    }
    Author "1" --> "*" Post : writes
    Collection "1" --> "*" Post : contains

甘特图 (Gantt Chart)

博客项目开发时间线：

gantt
    title 博客开发计划
    dateFormat  YYYY-MM-DD
    section 基础搭建
    项目初始化           :a1, 2026-06-01, 3d
    Astro 配置与主题     :a2, after a1, 4d
    section 内容系统
    Content Collections  :b1, after a2, 3d
    暗黑模式适配         :b2, after b1, 2d
    section 功能完善
    Mermaid 图表集成     :c1, after b2, 3d
    SEO 与 RSS          :c2, after c1, 2d
    Cloudflare 部署      :c3, after c2, 1d

状态图 (State Diagram)

展示一篇文章从草稿到发布的状态流转：

stateDiagram-v2
    [*] --> Draft: 新建文章
    Draft --> Review: 提交审核
    Review --> Draft: 需要修改
    Review --> Published: 审核通过
    Published --> Archived: 归档
    Published --> Draft: 撤回修改
    Archived --> [*]

ER 图 (Entity Relationship Diagram)

博客系统数据库关系：

erDiagram
    USER {
        int id PK
        string name
        string email
    }
    POST {
        int id PK
        string title
        text content
        date created_at
        int author_id FK
    }
    TAG {
        int id PK
        string name
    }
    POST_TAG {
        int post_id FK
        int tag_id FK
    }
    USER ||--o{ POST : writes
    POST ||--o{ POST_TAG : has
    TAG ||--o{ POST_TAG : belongs_to

饼图 (Pie Chart)

博客各板块文章数量占比示意：

pie title 文章板块分布
    "Claude 编程" : 8
    "提示词分享" : 5
    "软件分享" : 6
    "技术前沿" : 4
    "技术 Q&A" : 7

Git 图 (Git Graph)

展示 Git 分支与合并流程：

gitGraph
    commit id: "init"
    commit id: "add astro config"
    branch feature/mermaid
    checkout feature/mermaid
    commit id: "add mermaid plugin"
    commit id: "add dark theme"
    checkout main
    merge feature/mermaid
    branch feature/seo
    checkout feature/seo
    commit id: "add sitemap"
    commit id: "add rss"
    checkout main
    merge feature/seo
    commit id: "v1.0 release"

思维导图 (Mindmap)

技术博客架构全景：

mindmap
  root((AiX Docs))
    内容系统
      Content Collections
      Zod Schema
      Markdown 渲染
    前端
      Astro v5
      Tailwind CSS
      Shiki 高亮
      Mermaid 图表
    部署
      Git Push
      Cloudflare Pages
      CDN 加速
    功能
      暗黑模式
      RSS 订阅
      站点地图
      SEO 优化

总结

Mermaid.js 覆盖了技术写作中最常用的图表类型。关键优势：

  1. 纯文本可维护：图表和代码一起进入 Git 版本管理
  2. 自动化渲染：构建时或客户端自动转为 SVG
  3. 主题适配：通过 CSS 变量响应暗黑模式
  4. 零依赖图片：不需要导出 PNG/SVG 文件