28 Mermaid 渲染实战（VitePress）

1. 方案选择

当前采用“自定义组件 + mermaid 依赖”的方式：

• 组件文件：docs/.vitepress/theme/components/MermaidBlock.vue
• 注册入口：docs/.vitepress/theme/index.ts
• 依赖：mermaid

优点：可控、无额外渲染插件耦合、便于调试与回滚。

2. 使用方式

在 Markdown 中直接插入组件：

<MermaidBlock
  title="部署链路"
  chart="flowchart LR; A[Push main] --> B[GitHub Actions]; B --> C[Build docs]; C --> D[Cloudflare Pages];"
/>

3. 示例

Deploy Pipeline

Rendering diagram...

4. 常见失败与修复

• 失败：页面显示 Mermaid render failed。
  • 检查 chart 语法是否正确。
  • 检查 mermaid 依赖是否已安装。
• 失败：构建正常但图不显示。
  • 检查组件是否在 theme/index.ts 中注册。
  • 检查是否被 CSP 或脚本策略限制。

5. 回滚方案

• 临时回滚：将页面中的 <MermaidBlock .../> 改回纯文本代码块。
• 全量回滚：移除 theme/index.ts 中 Mermaid 组件注册与 mermaid 依赖。

6. 最佳实践

• 图表保持“小而清晰”，避免一图过长。
• 复杂流程拆成 2~3 张图，每张图配 3 行说明。
• 图标题统一命名规则，便于章节检索。