Mermaid 入门与进阶指南：从基础绘图到跨平台兼容策略

🧜‍♂️ Mermaid 入门与进阶指南：从基础绘图到跨平台兼容策略

一句话定义：
Mermaid 是一个基于 JavaScript 的“文本即图表”（Diagrams as Code）工具，允许你用类似 Markdown 的简洁语法，自动生成流程图、时序图、甘特图等专业可视化内容。

---

一、为什么使用 Mermaid？

• ✅ 纯文本驱动：图表可版本控制（Git 友好），告别二进制图片
• ✅ 高效修改：改几行代码，图表自动更新，无需拖拽对齐
• ✅ 生态集成：原生支持 Obsidian、Typora、GitLab、VS Code 等主流工具
• ✅ 开源免费：MIT 协议，社区活跃，持续迭代

---

二、基础功能（广泛兼容，推荐日常使用）

适用场景：GitHub、GitLab、Obsidian、Typora、VS Code 等大多数平台
特点：语法简单、渲染稳定、兼容性极强

1. 流程图（Flowchart）

graph TD
    A[开始] --> B{是否登录?}
    B -- 是 --> C[进入主页]
    B -- 否 --> D[跳转登录页]
    C --> E[结束]

• 方向控制：TD（Top-Down）、LR（Left-Right）
• 节点类型：
  • [矩形]：普通步骤
  • {菱形}：判断分支
  • ((圆形))：开始/结束（部分平台支持）
• 连线标签：A -- "是" --> B

2. 时序图（Sequence Diagram）

sequenceDiagram
    participant 用户
    participant 服务端
    用户->>服务端: 请求数据
    服务端-->>用户: 返回结果

• 参与者：participant A
• 消息类型：
  • ->>：同步请求（实线）
  • -->>：异步响应（虚线）

3. 甘特图（Gantt Chart）

gantt
    title 项目计划
    dateFormat  YYYY-MM-DD
    section 开发
    前端 :a1, 2026-02-01, 5d
    后端 :after a1, 7d

• 任务依赖：after task_id
• 时间格式：dateFormat YYYY-MM-DD

💡 基础功能优势：
几乎所有支持 Mermaid 的平台都能正确渲染，适合写技术文档、需求说明、系统设计。

---

三、高级功能（需特定环境支持）

适用场景：本地笔记软件（Obsidian/Typora）、自建文档站（Docusaurus/VitePress）
风险：在 GitHub、微信、Notion 等平台可能完全失效或显示为代码块

1. 高级节点形状

flowchart LR
    A[[子程序]] --> B[(数据库)]
    C{{六边形}} --> D[/梯形/]

• [[ ]]：子程序
• [( )]：圆柱体（数据库）
• {{ }}：六边形
• / /：平行四边形

⚠️ 注意：必须使用 flowchart，而非 graph

2. 样式与主题

%%{init: {'theme': 'forest'}}%%
flowchart LR
    classDef highlight fill:#f9f,stroke:#333;
    A[普通节点] --> B[高亮节点]
    class B highlight

• 自定义颜色、边框、字体
• 主题切换：default、forest、dark 等

3. 子图与分组

flowchart TB
    subgraph 模块A
        A --> B
    end
    subgraph 模块B
        C --> D
    end

4. 交互功能（Click 事件）

flowchart LR
    A[首页] --> B[帮助中心]
    click B "https://example.com" _blank

❗ 现实限制：

• GitHub 原生不支持 flowchart、classDef、subgraph
• Notion、飞书、微信公众号完全不支持 Mermaid 渲染

---

四、当平台不支持高级功能时：优雅降级策略

✅ 策略 1：坚持使用基础语法（推荐）

• 始终用 graph 而非 flowchart
• 避免 <br>，改用单行文本
• 用 emoji + 文字 替代图形语义：
  • 🗃️ 表示数据库
  • 🌐 表示服务器
  • 📱 表示移动端

graph LR
    A[📱 App] -->|HTTPS| B[🌐 Server]
    B --> C[🗃️ Database]

✅ 策略 2：生成静态图片插入

1. 在 Mermaid Live Editor 编写高级图表
2. 点击 Download → PNG/SVG
3. 将图片插入到不支持 Mermaid 的平台（如 GitHub README、PPT、Word）

✅ 优点：视觉效果完美，100% 兼容
❌ 缺点：无法版本控制，修改需重新导出

✅ 策略 3：条件化文档（高级用户）

在支持 Mermaid 的平台（如 GitLab）中保留代码，在不支持的平台提供图片 fallback：

<!-- 在 GitLab 中显示图表 -->
```mermaid
graph LR
    A --> B

<!-- 在 GitHub 中显示图片 -->
![外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传](https://img-home.csdnimg.cn/images/20230724024159.png?origin_url=.%2Fdiagram.png&pos_id=img-cVEE63rM-1770992473105)

---

五、各平台兼容性速查表

平台	支持 graph	支持 flowchart	支持样式/子图	建议方案
GitHub	✅	❌	❌	基础语法 + emoji
GitLab	✅	✅	✅	可用高级功能
Obsidian	✅	✅	✅	全功能可用
Typora	✅	✅	✅	全功能可用
VS Code	✅（需插件）	✅	✅	安装 Mermaid 插件
Notion	❌	❌	❌	导出 PNG 插入
微信公众号	❌	❌	❌	导出 PNG

---

六、总结：最佳实践建议

1. 日常写作优先使用基础语法（graph + [ ] + emoji）
2. 仅在可控环境（如个人笔记）使用高级功能
3. 对外发布文档（如 GitHub）一律降级为兼容模式
4. 复杂图表直接导出 PNG，确保万无一失

🎯 核心原则：
“能用最简语法表达清楚，就不要依赖高级特性。”
这样既能享受 Mermaid 的效率，又能避免兼容性陷阱。

---

通过以上策略，您可以在任何场景下安全、高效地使用 Mermaid，真正做到 “写一次，到处可用”。