Mermaid.js 服务端渲染终极指南：Node.js 生成静态图表的最佳实践

2026-02-05 04:49:21作者：董斯意

项目地址：https://gitcode.com/gh_mirrors/mer/mermaid

Mermaid.js 是一个基于 JavaScript 的图表绘制工具，使用类似 Markdown 的语法来生成流程图、时序图、甘特图等各种图表。虽然 Mermaid 主要在浏览器中运行，但通过服务端渲染技术，我们可以在 Node.js 环境中生成静态 SVG 图表，无需浏览器参与。🚀

为什么需要服务端渲染？

服务端渲染（SSR）为 Mermaid.js 带来了几个重要优势：

性能优化：预先生成图表，减少客户端计算负担
SEO 友好：搜索引擎可以直接索引生成的 SVG 内容
离线使用：生成静态文件供文档或演示使用
一致性：确保在不同环境中图表渲染结果一致

核心 API：mermaidAPI.render

Mermaid 提供了专门的 API 用于服务端渲染，核心方法是 mermaidAPI.render：

import mermaid from 'mermaid';

const { svg, bindFunctions } = await mermaid.render('graphDiv', `
  graph TD
    A[开始] --> B[处理数据]
    B --> C[生成图表]
    C --> D[完成]
`);

这个异步方法返回包含 SVG 代码和可选的绑定函数，非常适合服务端环境使用。

Node.js 环境配置

在 Node.js 中使用 Mermaid 需要特殊配置，因为缺少浏览器环境的 DOM API：

import { JSDOM } from 'jsdom';
import mermaid from 'mermaid';

// 创建虚拟 DOM 环境
const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>');
global.window = dom.window;
global.document = dom.window.document;
global.DOMPurify = require('dompurify')(dom.window);

// 初始化 Mermaid
mermaid.initialize({
  startOnLoad: false,
  securityLevel: 'loose'
});

完整的服务端渲染示例

下面是一个完整的 Node.js 服务端渲染示例：

const renderMermaid = async (diagramDefinition) => {
  try {
    const { svg } = await mermaid.render('mermaid-diagram', diagramDefinition);
    return svg;
  } catch (error) {
    console.error('图表渲染失败:', error);
    return null;
  }
};

// 使用示例
const flowchart = `
graph LR
  A[方形] --> B(圆角)
  B --> C{条件}
  C -->|是| D[结果1]
  C -->|否| E[结果2]
`;

const svgOutput = await renderMermaid(flowchart);
console.log(svgOutput);

高级配置选项

Mermaid 提供了丰富的配置选项来自定义图表外观：

mermaid.initialize({
  theme: 'dark',
  flowchart: {
    useMaxWidth: false,
    htmlLabels: true,
    curve: 'basis'
  },
  sequence: {
    diagramMarginX: 50,
    diagramMarginY: 10,
    actorMargin: 50
  },
  securityLevel: 'loose'
});

批量处理和缓存策略

对于需要处理大量图表的应用，建议实现缓存机制：

class MermaidRenderer {
  constructor() {
    this.cache = new Map();
  }

  async renderWithCache(key, diagramDefinition) {
    if (this.cache.has(key)) {
      return this.cache.get(key);
    }
    
    const svg = await this.renderDiagram(diagramDefinition);
    this.cache.set(key, svg);
    return svg;
  }

  async renderDiagram(definition) {
    // 渲染逻辑
  }
}