发布日期: 2025-12-15

在 Hexo 博客中优雅地集成 Mermaid 图表

在技术博客的创作过程中，纯文字的内容往往难以清晰展示业务流程、逻辑关系、项目进度与代码结构。而可视化图表能够直观呈现复杂内容，大幅提升文章的可读性与专业性。本文将详细讲解Hexo 博客集成 Mermaid 图表的完整实操方案，无需复杂绘图工具，仅通过简洁的文本语法，即可在 Markdown 中快速生成各类精美交互式图表。

一、什么是 Mermaid？

Mermaid 是一款轻量、高效的 JavaScript 图表绘制工具，核心优势是文本绘图。用户无需拖拽作图，只需编写简单易懂的类 Markdown 语法，就能自动渲染生成 SVG 格式的高清交互式图表。

其全面覆盖技术写作常用图表类型，包含：流程图、时序/序列图、甘特图、类图、状态图、饼图等，完美适配技术博客、文档笔记、项目复盘等各类场景，是技术创作者的必备工具。

二、Hexo 集成 Mermaid 完整方案

原生 Hexo 不支持 Mermaid 语法渲染，需要通过替换渲染插件、安装依赖、配置主题参数三步完成适配。以下为亲测可用、无冲突的完整部署步骤。

1. 安装 & 卸载依赖（解决渲染冲突）

Hexo 默认的 hexo-renderer-marked渲染器不兼容 Mermaid 语法，会导致图表无法渲染、代码乱码，因此需要替换为适配性更强的 markdown-it渲染器，并安装 Mermaid 专属标签插件。

推荐使用 pnpm 执行命令（速度快、依赖整洁）：

# 安装适配Mermaid的渲染器与标签插件
pnpm install hexo-renderer-markdown-it hexo-tag-mermaid --save

# 卸载原生冲突渲染器（必做，否则渲染失效）
pnpm uninstall hexo-renderer-marked

2. 主题配置文件开启 Mermaid 支持

以主流的 matery 主题为例，修改主题配置文件 themes/hexo-theme-matery/_config.yml，新增或修改 Mermaid 全局配置，开启渲染功能并自定义图表样式：

mermaid: ## Mermaid官方仓库：https://github.com/knsv/mermaid
  enable: true  # 开启Mermaid渲染功能
  version: "latest" # 调用最新版本内核
  options:  # 全局图表样式配置
    theme: default # 默认主题，支持dark/neutral/base
    gantt: { axisFormat: '%Y-%m-%d' } # 甘特图日期格式
    sequence: { actorMargin: 50 } # 序列图角色间距

3. Hexo 主配置文件适配渲染规则

修改博客根目录的 _config.yml 主配置文件，配置 markdown-it 渲染规则，兼容Mermaid语法，同时保留丰富的Markdown拓展功能：

markdown:
  render:
    html: true
    xhtmlOut: false
    breaks: false
    linkify: true
    typographer: true
    quotes: '"""''
  plugins:
    - markdown-it-abbr
    - markdown-it-footnote
    - markdown-it-ins
    - markdown-it-sub
    - markdown-it-sup
  anchors:
    level: 2
    collisionSuffix: 'v'
    permalink: true
    permalinkClass: 'header-anchor'
    permalinkSide: 'left'
    permalinkSymbol: '#'
    case: 0
    separator: '-'

# Mermaid全局配置
mermaid:
  enable: true
  version: "latest"
  options:
    theme: default
    gantt: { axisFormat: '%Y-%m-%d' }
    sequence: { actorMargin: 50 }

配置完成后，执行 hexo clean && hexo g && hexo s 重启本地服务，即可生效Mermaid图表渲染功能。

三、常用 Mermaid 图表实战示例

以下整理了技术博客最常用的5类图表，代码可直接复制使用，无乱码、可正常渲染，适配上述配置环境。

1. 基础流程图

适用于业务流程、逻辑判断、操作步骤展示，支持横向（LR）、纵向（TD）布局。

纵向流程示例：

{% mermaid %}
graph TD
    A[开始] --> B{条件判断}
    B -->|是| C[执行操作A]
    B -->|否| D[执行操作B]
    C --> E[流程结束]
    D --> E
{% endmermaid %}

横向业务流程示例：

{% mermaid %}
graph LR
    程序启动 --> 接收用户数据
    接收用户数据 --> 格式验证
    格式验证 -->|验证通过| 业务逻辑处理
    格式验证 -->|验证失败| 返回错误提示
    业务逻辑处理 --> 数据持久化存储
    数据持久化存储 --> 流程结束
    返回错误提示 --> 流程结束
{% endmermaid %}

2. 序列图（时序图）

适用于展示前后端交互、多角色通信、接口请求流程，清晰呈现请求与响应时序关系。

{% mermaid %}
sequenceDiagram
    participant 客户端
    participant 服务端
    participant 数据库
    客户端 ->> 服务端: 发送业务请求
    服务端 ->> 数据库: 查询对应业务数据
    数据库 -->> 服务端: 返回查询结果
    服务端 -->> 客户端: 响应最终业务数据
{% endmermaid %}

3. 甘特图（项目进度图）

适用于项目管理、任务排期、进度复盘，直观展示各阶段任务时间与依赖关系。

{% mermaid %}
gantt
    dateFormat  YYYY-MM-DD
    title 项目开发整体进度规划
    section 需求设计阶段
    需求调研分析     :active, a1, 2023-01-01, 7d
    整体系统设计     :after a1, 10d
    section 代码开发阶段
    前端页面开发     :2023-01-18, 14d
    后端接口开发     :2023-01-18, 14d
    section 测试上线阶段
    单元功能测试     :after 前端页面开发, 7d
    整体集成测试     :after 单元功能测试, 7d
{% endmermaid %}

4. 类图（结构关系图）

适用于后端开发、程序设计，展示类的属性、方法以及继承、关联关系。

{% mermaid %}
classDiagram
    class 动物 {
        + String 名称
        + int 年龄
        + void 进食()
        + void 移动()
    }
    
    class 狗狗 {
        + String 品种
        + void 吠叫()
    }
    
    狗狗 --|> 动物
{% endmermaid %}

5. 状态图

适用于展示业务状态流转、审核流程、任务生命周期等状态切换逻辑。

{% mermaid %}
stateDiagram-v2
    [*] --> 待审核
    待审核 --> 审核中: 提交申请
    审核中 --> 审核通过: 校验合规
    审核中 --> 审核驳回: 校验异常
    审核通过 --> 执行中: 启动任务
    执行中 --> 任务完成: 流程执行完毕
    审核驳回 --> 待审核: 修改后重新提交
    任务完成 --> [*]
{% endmermaid %}