给 Astro 博客添加 Mermaid 图表支持：5分钟搞定，效果惊艳

May 7, 2026

一、为什么我要在博客中添加 Mermaid

写技术博客的时候，你是不是也遇到过这种情况？

想描述一个复杂的业务流程或者算法逻辑，写了一大堆文字，读者还是看不太懂。画个流程图吧，又要打开各种绘图工具，导出图片还要上传，改起来特别麻烦。

我曾经也和你一样，在技术文章中描述流程全靠文字堆砌，读者反馈说”有点绕，看不太懂”。

直到我发现了 Mermaid —— 一个用纯文本就能画图表的神器。

今天这篇文章，我将从为什么选择 Mermaid、安装配置过程、实际使用效果三个方面，详细分享我给博客添加 Mermaid 支持的完整经历。

二、Mermaid 到底好在哪里

2.1 纯文本，易于版本管理

Mermaid 最大的优势就是纯文本格式。你不需要任何外部绘图工具，直接在 Markdown 里就能写图表。

	graph LR
		A[写代码] --> B[提交Git]
		B --> C[自动渲染]

这意味着：

✅ 和代码一起提交到 Git，历史记录完整
✅ 修改图表就像改代码一样简单
✅ 不需要额外的图片文件，减少依赖

2.2 支持多种图表类型

Mermaid 支持的图表类型非常丰富，完全覆盖技术博客的需求：

图表类型	用途	我是否常用
流程图	业务流程、算法逻辑	⭐⭐⭐⭐⭐
时序图	API 调用、消息交互	⭐⭐⭐⭐
类图	面向对象设计	⭐⭐⭐
状态图	状态机、生命周期	⭐⭐⭐
饼图	数据统计、占比分析	⭐⭐⭐
甘特图	项目排期、时间线	⭐⭐

2.3 零成本，社区活跃

Mermaid 是完全开源的，GitHub 上有超过 60k+ stars，社区非常活跃。很多主流平台（GitHub、Notion、GitBook）都已经原生支持 Mermaid。

三、在 Astro 中安装配置 Mermaid

3.1 安装依赖

第一步很简单，安装 Mermaid 相关的包：

npm install mermaid astro-mermaid

💡 说明：

mermaid 是核心渲染库

astro-mermaid 是适配 Astro 的安装支架

3.2 配置 Markdown 渲染

在 astro.config.mjs 中添加对 Mermaid 的支持：

// astro.config.mjs
import { defineConfig } from 'astro/config';
import mermaid from 'astro-mermaid';

export default defineConfig({
  integrations: [
    mermaid({
      theme: 'forest',
      autoTheme: true
    })
  ]
});

3.4 创建自定义代码块渲染器

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

✅ 配置完成！ 整个过程不到 5 分钟，非常简单。

四、实际使用效果展示

配置完成后，让我给你展示几个实际的渲染效果。

4.1 流程图：博客发布流程

这是我博客文章的发布流程，用 Mermaid 画出来一目了然：

graph LR
    A([开始写稿]) --> B[Obsidian编辑]
    B --> C[Hermes AI润色]
    C --> D{质量检查}
    D -- 不通过 --> B
    D -- 通过 --> E[同步到博客仓库]
    E --> F[GitHub Actions构建]
    F --> G[自动部署]
    G --> H([发布完成])
    
    classDef startend fill:#4CAF50,stroke:#388E3C,color:white
    classDef process fill:#2196F3,stroke:#1565C0,color:white
    classDef decision fill:#FF9800,stroke:#EF6C00,color:white
    
    class A,H startend
    class B,C,E,F,G process
    class D decision

📊 效果说明： 整个发布流程清晰可见，每一步做什么都一目了然。配上不同的颜色，重点步骤一眼就能识别。

4.2 时序图：用户登录流程

这是一个典型的用户登录时序图，展示了各个系统之间的交互：

sequenceDiagram
    participant 用户
    participant 前端
    participant API网关
    participant 认证服务
    participant 数据库
    
    用户->>前端: 输入账号密码
    前端->>前端: 表单验证
    前端->>API网关: POST /api/login
    API网关->>认证服务: 验证凭证
    认证服务->>数据库: 查询用户信息
    数据库-->>认证服务: 返回用户数据
    认证服务->>认证服务: 密码哈希验证
    认证服务-->>API网关: 生成JWT Token
    API网关-->>前端: 返回登录结果
    前端-->>用户: 登录成功，跳转到主页

📊 效果说明： 时序图完美展示了登录过程中各个环节的调用关系，比文字描述清晰 10 倍！

4.3 状态图：文章状态流转

博客文章从草稿到发布的状态流转，用状态图展示非常直观：

stateDiagram-v2
    [*] --> 草稿
    
    草稿 --> 待审核: 提交审核
    待审核 --> 草稿: 需要修改
    待审核 --> 已发布: 审核通过
    
    已发布 --> 已归档: 下架/过期
    已归档 --> 已发布: 重新发布
    
    草稿 --> 已删除: 放弃
    待审核 --> 已删除: 拒绝
    
    已删除 --> [*]

📊 效果说明： 状态流转一目了然，每个状态之间的转换关系都清晰地展示出来了。

4.4 饼图：博客内容分类统计

看看我博客的内容分类统计，用饼图展示数据占比：

pie title 2024年博客文章分类
    "技术教程" : 45
    "个人成长" : 25
    "工具评测" : 15
    "生活随笔" : 15

📊 效果说明： 数据可视化就是这么简单，不需要任何图表库，一行代码搞定。

五、使用体验与优化建议

5.1 实际使用感受

用了一周 Mermaid，我最大的感受就是：太香了！

✅ 写文章更快了 - 不需要切换到绘图工具，边写边画
✅ 修改更方便 - 改图表就像改代码，几秒钟搞定
✅ 文章更专业 - 有图表的技术文章读起来轻松很多
✅ 读者反馈更好 - 好几个人留言说图表帮他们理解了复杂概念

5.2 几个优化建议

建议 1：统一图表方向

对于大多数博客场景，推荐使用 LR（从左到右） 布局，因为：

垂直空间占用少，移动端阅读体验更好
符合中文从左到右的阅读习惯
图表整体更紧凑

graph LR
    A[推荐使用] --> B[LR 方向布局]

建议 2：控制图表大小

一张图的节点数量建议控制在 3-15 个 之间：

太少：没必要画图
太多：图表太挤，看不清
超过 15 个节点：考虑拆分成多张图

建议 3：使用颜色区分节点

给不同类型的节点加上不同的颜色，阅读体验会好很多：

graph LR
    A[开始]:::success --> B{判断}:::warning
    B --> C[成功]:::success
    B --> D[失败]:::danger
    
    classDef success fill:#4CAF50,stroke:#388E3C,color:white
    classDef warning fill:#FF9800,stroke:#EF6C00,color:white
    classDef danger fill:#F44336,stroke:#D32F2F,color:white

建议 4：图表前后加文字说明

不要孤零零地放一张图，前后要有过渡和说明：

用户登录时，系统会执行以下验证流程：

graph LR
    A[...] --> B[...]

📊 说明： 上图展示了完整的登录验证流程，其中密码验证是关键环节。

接下来我们看看…

六、常见问题与解决方案

Q1：图表渲染不出来怎么办？

可能原因：

Mermaid 没有正确初始化
代码有语法错误（括号不匹配等）
节点 ID 重复了

解决方案：

打开浏览器控制台看报错信息
用 Mermaid Live Editor 在线验证语法

Q2：图表太大，移动端显示不全怎么办？

解决方案：

优先使用 LR（左右）布局
减少节点数量，拆分图表
给容器加 overflow-x: auto

Q3：想自定义主题配色怎么办？

解决方案：
Mermaid 支持自定义主题，在初始化时配置：

mermaid.initialize({
  theme: 'base',
  themeVariables: {
    primaryColor: '#4F46E5',
    primaryTextColor: '#fff',
    lineColor: '#6B7280',
  }
});

📝 后记： 写这篇文章的时候，所有图表都是直接在 Markdown 里写的，写完就看到效果，整个体验非常流畅。这就是 Mermaid 的魅力 —— 让技术写作变得更简单、更快乐。