mermaid-graph-renderer

Mermaid 图表渲染器

在 Web 和离线环境中，将 Mermaid 图表渲染为可用于生产环境的 SVG、PNG 和 PDF。涵盖从延迟加载的客户端渲染到速度快达 1000 倍的原生 Rust 批量导出的全方位方案。

核心限制

Mermaid.js 需要浏览器 API（document.createElement、SVGTextElement.getBBox()）来计算文本尺寸。所有非浏览器渲染路径都必须嵌入无头浏览器，或从头重新实现渲染器。以下所有决策都受到这一限制的影响。

---

适用场景

✅ 适用于：

• 在网页上渲染 Mermaid 图表（经过性能优化）
• 将图表导出为 SVG、PNG 或 PDF（离线／命令行）
• 搭建用于生成图表图像的 CI/CD 流水线
• 为项目选择渲染库
• 优化文档网站上的 Mermaid 加载时间

❌ 不适用于：

• 编写 Mermaid 语法（使用 mermaid-graph-writer）
• 渲染非 Mermaid 格式（PlantUML、GraphViz——参见 Kroki）
• 通用图像处理或编辑

---

渲染决策树

flowchart TD
  A{Where are you rendering?} -->|Browser| B{Performance matters?}
  A -->|CLI / CI| C{Volume?}
  A -->|Server-side| D{Must avoid client JS?}

  B -->|Yes| E[Lazy-load mermaid.js]
  B -->|No| F[CDN script tag]

  C -->|1-10 diagrams| G[mermaid-cli]
  C -->|10-100 diagrams| H{Need multiple formats?}
  C -->|100+ diagrams| I[mmdr Rust renderer]

  H -->|Mermaid only| G
  H -->|Multiple languages| J[Kroki]

  D -->|Yes, zero JS| K[Build-time with Puppeteer]
  D -->|Some JS OK| E
  K -->|Slow builds warning| L[rehype-mermaid + Playwright]

---

Web 渲染

方案 1：延迟加载 mermaid.js（推荐）

最适合只有部分页面包含图表的文档网站、博客和应用。

工作原理：先检查是否存在 .mermaid 元素，再加载库。只有实际需要渲染图表的页面才会承担约 480 KB 的开销。

// Lazy load pattern — only loads mermaid.js when diagrams exist
function initMermaid() {
  const diagrams = document.querySelectorAll('.mermaid');
  if (diagrams.length === 0) return;

  const script = document.createElement('script');
  script.src = 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js';
  script.onload = () => {
    mermaid.initialize({ startOnLoad: false, theme: 'neutral' });
    mermaid.run({ nodes: diagrams });
  };
  document.head.appendChild(script);
}

// Handle initial load + SPA navigation
document.addEventListener('DOMContentLoaded', initMermaid);
// For SPA route changes: call initMermaid() after navigation

要点：对于初始页面加载和客户端导航（SPA 路由变化），都要在新图表内容出现时重新运行 mermaid.run()。

方面	值
包体积	约 480 KB（核心库 + 延迟加载的图表分块）
渲染时间	每个图表约 50-200 ms（客户端）
图表支持	完整（所有 Mermaid 类型）
最适合	文档网站、博客、偶尔包含图表的应用

方案 2：@mermaid-js/tiny

用于 CDN 的预打包子集。包含所有图表类型，不会延迟加载图表分块。总体体积更小，但会立即加载。

适用场景：明确只需要 1-2 种图表类型，并希望通过单文件导入。

方案 3：构建时 SSR（通常不值得）

使用 Puppeteer/Playwright 在构建时渲染 SVG。听起来很吸引人，实际使用却很麻烦。

代价：

• 会使 node_modules 增加约 280 MB（Puppeteer + Chromium）
• 每个图表需要约 2-3 秒来启动并完成渲染
• 构建 30 个左右的图表，会让 5 秒的构建时间变成 45 秒
• Docker/CI 问题（需要安装 Chrome）

真正值得采用的场景：严格要求零 JS，或网站包含数百个图表，且希望完全消除客户端渲染。

工具：rehype-mermaid（使用 Playwright）、rehype-mermaid-cli（封装官方 CLI）。

结论：除非严格要求零 JS，否则延迟加载的客户端渲染是更好的折中方案。

---

离线／命令行渲染

方案 1：mermaid-cli（官方）

官方 CLI 工具。启动无头 Chromium，完成渲染并捕获输出。

# Install
npm install -g @mermaid-js/mermaid-cli

# Basic usage
mmdc -i input.mmd -o output.svg
mmdc -i input.mmd -o output.png -b transparent
mmdc -i input.mmd -o output.pdf

# With config
mmdc -i input.mmd -o output.svg -t dark --configFile mermaid.config.json

# Batch: process Markdown with embedded diagrams
mmdc -i document.md -o document-with-images.md

# Docker
docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.svg

方面	值
速度	每个图表约 3000 ms（Chromium 开销）
输出	SVG、PNG、PDF
体积	约 280 MB（Puppeteer + Chromium）
支持范围	完整（所有 Mermaid 类型，100% 一致）
最适合	1-50 个图表，尤其注重准确性的场景

SVG 注意事项：输出的 SVG 包含 <foreignObject> 元素，在 Inkscape 和 rsvg-convert 中会出问题。解决方法：在配置中设置 "htmlLabels": false，或改为导出 PNG。

方案 2：Kroki（多格式网关）

统一的 HTTP API，可将图表源码路由到相应的渲染引擎。支持 25+ 种语言（Mermaid、PlantUML、GraphViz、D2、Excalidraw 等）。

# Render via HTTP (self-hosted or kroki.io)
curl -X POST https://kroki.io/mermaid/svg \
  -H 'Content-Type: text/plain' \
  -d 'flowchart LR
    A --> B --> C' \
  -o diagram.svg

# Self-host via Docker Compose
# docker-compose.yml needs: yuzutech/kroki + yuzutech/kroki-mermaid

方面	值
速度	约 500-2000 ms（网络 + 渲染）
输出	SVG、PNG、PDF、JPEG
语言	25+ 种（Mermaid、PlantUML、GraphViz、D2 等）
最适合	多语言流水线、CI/CD、文档生成器

Kroki 更合适的场景：需要在同一条流水线中使用多种图表语言。 不适用的场景：简单的“渲染一个 Mermaid 图表”——功能过剩。

选项 3：mmdr（原生 Rust — 速度最快）

使用原生 Rust 重新实现。无需浏览器或 Node.js。速度约为 mermaid-cli 的 1000 倍。

# Install (Rust toolchain required)
cargo install mmdr

# Usage
mmdr input.mmd -o output.svg
mmdr input.mmd -o output.png  # via resvg, no browser

方面	值
速度	每张图表约 3 ms（快 1000 倍）
输出	SVG（原生）、PNG（通过 resvg）
大小	二进制文件约 5-10 MB
覆盖范围	13 种图表类型（部分功能对等）
最适合	批量处理 100 张以上图表、提升 CI/CD 速度

权衡：目前尚未支持所有 Mermaid 功能。流程图和时序图已较为成熟；其他类型的支持程度不一。若要追求速度，请接受一些不完善之处；若遇到特殊情况，可回退到 mermaid-cli。

没有 <foreignObject> 问题：使用原生 SVG 文本，因此输出可用于 Inkscape 和其他 SVG 工具。

---

对比矩阵

标准	mermaid.js CDN	mermaid-cli	Kroki	mmdr (Rust)
运行环境	浏览器	Node + Puppeteer	Docker	原生二进制文件
速度/图表	约 100 ms	约 3000 ms	约 1000 ms	约 3 ms
SVG 质量	极佳	极佳	极佳	良好（持续改进中）
PNG 质量	不适用	良好	良好	良好（resvg）
PDF 导出	不适用	支持	支持	尚未支持
安装大小	约 480 KB	约 280 MB	约 1 GB（Docker）	约 5-10 MB
图表覆盖范围	完整	完整	完整	13 种类型
适合 CI/CD	较差	一般	良好	极佳
多语言	否	否	是（25 种以上）	否

---

按使用场景给出的建议

使用场景	建议	原因
偶尔包含图表的文档网站	延迟加载 mermaid.js	仅在需要的页面加载
Next.js / SSR 应用	动态导入，ssr: false	不要与构建时渲染较劲
CI/CD 生成静态文档（仅 Mermaid）	追求速度用 mmdr，追求准确性用 mermaid-cli	速度快 1000 倍 vs. 100% 功能对等
CI/CD 处理多种图表语言	Kroki	一个 API 即可处理 PlantUML + Mermaid + GraphViz
批量导出用于打印/PDF（100 张以上图表）	mmdr + mermaid-cli 回退方案	大多数情况处理快速，特殊情况确保准确
桌面应用（Electron/Obsidian/VS Code）	内置 mermaid.js	已内嵌 Chromium

---

反模式

执着于 SSR

错误：花 3 天时间在 CI 中配置 Puppeteer，只为避免 480 KB 的客户端 JS。 正确：延迟加载 mermaid.js。只有包含图表的页面才会获取这 480 KB。大多数用户不会注意到。

意外遇到 foreignObject

错误：从 mermaid-cli 导出 SVG，却纳闷 Inkscape 为什么打不开。 正确：在配置中设置 "htmlLabels": false，或者直接导出为 PNG。

什么都用同一个工具

错误：在 CI 中用 mermaid-cli 处理 500 张图表（构建耗时 25 分钟）。 正确：批量处理使用 mmdr；只有少数需要完整功能对等的图表才使用 mermaid-cli。