Fumadocs 项目中 Mermaid 图表渲染的最佳实践

问题背景

在 Fumadocs 项目中使用 Mermaid 图表时，开发者可能会遇到一个常见的渲染问题：当 Mermaid 图表被放置在可切换的 Tab 组件中时，首次渲染正常，但在切换标签页后再次返回时，控制台会抛出"无法读取 null 的属性(firstChild)"的错误。

问题根源分析

这个问题的根本原因在于 Mermaid 渲染 API 的使用方式与 React 组件生命周期的冲突。具体表现为：

1. 官方示例中直接将 DOM 容器引用传递给 mermaid.render 方法
2. 当组件被卸载时(如切换 Tab)，React 会清理 DOM 节点
3. 再次渲染时，Mermaid 尝试操作已被清理的 DOM 节点，导致错误

解决方案

正确的做法是遵循 React 的数据驱动原则，避免直接操作 DOM。以下是改进后的实现方案：

1. 仅使用 mermaid.render 生成 SVG 字符串
2. 通过 React 的 dangerouslySetInnerHTML 安全地插入 SVG
3. 完全控制组件的挂载和卸载过程

实现代码示例

'use client';
import { useEffect, useId, useState } from 'react';
import type { MermaidConfig } from 'mermaid';
import { useTheme } from 'next-themes';

export function Mermaid({ chart, title }: { chart: string; title?: string }) {
  const id = useId();
  const [svg, setSvg] = useState('');
  const { resolvedTheme } = useTheme();

  useEffect(() => {
    let isMounted = true;
    void renderChart();

    async function renderChart() {
      const mermaidConfig: MermaidConfig = {
        startOnLoad: false,
        securityLevel: 'loose',
        fontFamily: 'inherit',
        themeCSS: 'margin: 1.5rem auto 0;',
        theme: resolvedTheme === 'dark' ? 'dark' : 'default',
      };
      const { default: mermaid } = await import('mermaid');
      try {
        mermaid.initialize(mermaidConfig);
        const { svg } = await mermaid.render(
          id.replaceAll(':', ''),
          chart.replaceAll('\\n', '\n')
        );
        if (isMounted) setSvg(svg);
      } catch (error) {
        console.error('Mermaid 渲染错误', error);
      }
    }
    return () => {
      isMounted = false;
      setSvg('');
    };
  }, [chart, id, resolvedTheme]);

  return (
    <div>
      <div dangerouslySetInnerHTML={{ __html: svg }} />
      {title && <div>{title}</div>}
    </div>
  );
}

关键改进点

1. 状态管理：使用 useState 管理 SVG 字符串，完全遵循 React 的数据流
2. 生命周期控制：通过 isMounted 标志确保组件卸载时不会更新状态
3. 主题适配：集成 next-themes 实现暗黑/明亮主题自动切换
4. 错误处理：捕获并记录渲染过程中的错误
5. 清理机制：组件卸载时重置 SVG 状态

使用建议

1. 在 Tab 组件中使用时，确保每个 Mermaid 实例有唯一的 key
2. 对于复杂图表，考虑添加加载状态提示
3. 图表内容变化时，组件会自动重新渲染
4. 主题切换时会自动重新生成适配当前主题的图表

总结

通过这种方式实现的 Mermaid 组件不仅解决了 Tab 切换时的渲染问题，还具有更好的可维护性和扩展性。它完全遵循 React 的设计哲学，避免了直接 DOM 操作带来的副作用，是集成 Mermaid 到 React 项目中的推荐做法。