Mermaid 图表
使用 Mermaid 在 Markdown 中绘制专业图表，无需图片编辑工具。
为什么使用 Mermaid？
- 纯文本编写：代码即图表，版本可追踪
- 多种图表：流程图、序列图、甘特图、类图、饼图等 20+ 类型
- 主题适配：自动适配 VitePress 亮色/暗色模式
- 维护方便：修改代码即可更新图表，无需重新导出图片
安装配置
安装插件
bash
npm install vitepress-plugin-mermaid mermaid -D配置 VitePress
ts
// .vitepress/config.mts
import { withMermaid } from 'vitepress-plugin-mermaid'
export default withMermaid({
// 你的 VitePress 配置
themeConfig: {
// ...
},
mermaid: {
// Mermaid 配置（可选）
}
})注册 Mermaid 组件（可选）
如果需要在 Vue 组件中使用 Mermaid：
ts
// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import { Mermaid } from 'vitepress-plugin-mermaid'
export default {
extends: DefaultTheme,
enhanceApp({ app }) {
app.component('Mermaid', Mermaid)
}
}基础用法
在 Markdown 中使用 mermaid 代码块：
markdown
```mermaid
graph TD
A[开始] --> B{判断条件}
B -->|是| C[执行操作]
B -->|否| D[结束]
C --> D
```渲染效果：
mermaid
graph TD
A[开始] --> B{判断条件}
B -->|是| C[执行操作]
B -->|否| D[结束]
C --> D流程图
方向控制
| 关键字 | 方向 | 说明 |
|---|---|---|
TB | 从上到下 | 默认 |
BT | 从下到上 | |
LR | 从左到右 | |
RL | 从右到左 |
节点形状
mermaid
graph TD
A[矩形] --> B(圆角矩形)
B --> C{菱形}
C --> D[(数据库)]
D --> E[[子程序]]
E --> F[(圆柱体)]
F --> G>旗帜]markdown
A[矩形] -- 默认形状
B(圆角矩形) -- 圆角
C{菱形} -- 判断/条件
D[(数据库)] -- 数据库
E[[子程序]] -- 子程序
F[(圆柱体)] -- 圆柱
G>旗帜] -- 旗帜连线样式
mermaid
graph LR
A -->|实线箭头| B
B ---|实线无箭头| C
C -.-|虚线| D
D ==>|粗线| E
E -- 文字标签 --> F子图
mermaid
graph TB
subgraph 前端
A[Vue 组件] --> B[VitePress]
end
subgraph 构建
C[Vite] --> D[Markdown]
end
B --> C序列图
用于展示对象间的交互顺序：
mermaid
sequenceDiagram
participant 用户
participant 浏览器
participant 服务器
用户->>浏览器: 访问页面
浏览器->>服务器: HTTP 请求
服务器-->>浏览器: 返回 HTML
浏览器-->>用户: 渲染页面
Note right of 服务器: SSG 预渲染<br/>静态文件直接返回消息类型
| 语法 | 样式 | 说明 |
|---|---|---|
->> | 实线箭头 | 同步请求 |
-->> | 虚线箭头 | 返回响应 |
--) | 实线无箭头 | 异步消息 |
--) | 虚线无箭头 | 异步返回 |
激活框
mermaid
sequenceDiagram
participant Client
participant Server
Client->>Server: 请求
activate Server
Server-->>Client: 响应
deactivate Server甘特图
用于项目时间线规划：
mermaid
gantt
title VitePress 项目计划
dateFormat YYYY-MM-DD
axisFormat %m/%d
section 准备
需求分析 :a1, 2026-01-01, 7d
技术选型 :a2, after a1, 3d
section 开发
主题定制 :b1, after a2, 10d
内容编写 :b2, after a2, 20d
section 发布
测试验收 :c1, after b1, 5d
正式上线 :milestone, after c1, 0d任务状态
markdown
任务名 :active, 2026-01-01, 7d # 进行中
任务名 :done, 2026-01-01, 7d # 已完成
任务名 :crit, 2026-01-01, 7d # 关键任务
任务名 :milestone, 2026-01-15, 0d # 里程碑类图
用于展示系统架构和类关系：
mermaid
classDiagram
class VitePress {
+config: SiteConfig
+theme: Theme
+build(): Promise~void~
+dev(): Promise~void~
}
class Theme {
+Layout: Component
+enhanceApp(): void
}
class SiteConfig {
+title: string
+description: string
+themeConfig: ThemeConfig
}
VitePress --> Theme : 使用
VitePress --> SiteConfig : 读取饼图
mermaid
pie title VitePress 内容类型分布
"入门指南" : 15
"基础功能" : 25
"主题定制" : 20
"高级功能" : 25
"实战案例" : 15状态图
mermaid
stateDiagram-v2
[*] --> 草稿
草稿 --> 审核中: 提交审核
审核中 --> 已发布: 审核通过
审核中 --> 草稿: 驳回修改
已发布 --> 草稿: 撤回
已发布 --> [*]ER 图
用于数据库关系建模：
mermaid
erDiagram
ARTICLE ||--o{ COMMENT : has
ARTICLE {
string title
string content
date publishedAt
}
COMMENT {
string content
date createdAt
}
AUTHOR ||--o{ ARTICLE : writes
AUTHOR {
string name
string email
}主题适配
亮色/暗色模式
VitePress 插件会自动根据当前主题切换 Mermaid 样式。如需自定义：
ts
// .vitepress/config.mts
export default withMermaid({
mermaid: {
theme: 'default' // 'default' | 'dark' | 'forest' | 'neutral'
}
})CSS 变量覆盖
css
/* .vitepress/theme/styles/mermaid.css */
.mermaid {
/* 图表字体 */
font-family: var(--vp-font-family-base);
}
/* 节点样式 */
.mermaid .node rect {
fill: var(--vp-c-brand-soft) !important;
stroke: var(--vp-c-brand-1) !important;
}在 Vue 组件中使用
vue
<script setup lang="ts">
import { Mermaid } from 'vitepress-plugin-mermaid'
const chart = `graph TD
A[开始] --> B[结束]
`
</script>
<template>
<Mermaid :value="chart" />
</template>常见问题
图表不渲染？
- 确认已安装
vitepress-plugin-mermaid和mermaid - 确认配置使用了
withMermaid包装 - 检查代码块语法是否正确
构建报错？
Mermaid 插件在 SSR 阶段可能出错，使用动态导入：
ts
// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
export default {
extends: DefaultTheme,
enhanceApp({ app }) {
if (typeof window !== 'undefined') {
import('vitepress-plugin-mermaid').then(({ Mermaid }) => {
app.component('Mermaid', Mermaid)
})
}
}
}中文显示问题？
配置 Mermaid 使用支持中文的字体：
ts
export default withMermaid({
mermaid: {
themeVariables: {
fontFamily: '"Inter", "Noto Sans SC", system-ui, sans-serif'
}
}
})最佳实践
| 场景 | 推荐图表 | 说明 |
|---|---|---|
| 逻辑流程 | 流程图 graph | 条件分支、循环 |
| 交互顺序 | 序列图 sequenceDiagram | API 调用、用户操作 |
| 时间规划 | 甘特图 gantt | 项目排期 |
| 系统架构 | 类图 classDiagram | 代码结构 |
| 数据占比 | 饼图 pie | 分类统计 |
| 状态流转 | 状态图 stateDiagram-v2 | 工作流、生命周期 |
| 数据模型 | ER 图 erDiagram | 数据库设计 |
下一步
本章检查清单
0 / 8 已完成0%