Fumadocs项目中Mermaid图表渲染问题的分析与解决方案

问题背景

在使用Fumadocs项目构建文档系统时，开发人员发现当HTML元素的属性发生变化但主题保持不变时，Mermaid图表会无法正常渲染。具体表现为：

1. 在系统主题为亮色模式下，将主题从"系统"切换到"亮色"或反之，Mermaid元素会消失
2. 当使用shadcn/ui的抽屉组件时，由于组件添加了scroll-behavior: auto样式，Mermaid图表也会消失
3. 从暗色切换到亮色主题时却能正常渲染

技术分析

经过深入分析，这个问题根源在于@theguild/remark-mermaid库的实现方式。该库在渲染Mermaid图表时，对DOM变化的处理不够完善，导致在某些属性变化时无法正确重新渲染。

核心问题点包括：

1. 主题切换时，虽然实际主题未变，但HTML元素的属性变化触发了重新渲染
2. 库内部可能依赖某些DOM状态，当这些状态变化时未能正确处理
3. 使用innerHTML直接渲染SVG可以规避此问题，说明问题出在渲染机制上

解决方案

针对这一问题，可以采用自定义Mermaid组件的方案，完全控制渲染流程：

'use client';

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

export function Mermaid({ chart }: { chart: string }) {
  const id = useId();
  const [svg, setSvg] = useState('');
  const containerRef = useRef<HTMLDivElement>(null!);
  const { resolvedTheme } = useTheme();

  useEffect(() => {
    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'),
          containerRef.current,
        );
        setSvg(svg);
      } catch (error) {
        console.error('Error while rendering mermaid', error);
      }
    }
  }, [chart, id, resolvedTheme]);

  return <div ref={containerRef} dangerouslySetInnerHTML={{ __html: svg }} />;
}

实现要点

1. 主题感知：组件通过useTheme钩子感知当前主题，自动切换Mermaid的亮/暗主题
2. 安全渲染：使用dangerouslySetInnerHTML直接注入SVG，避免中间渲染环节的问题
3. 错误处理：包含完整的错误捕获机制，确保渲染失败时不会影响整体应用
4. React版本兼容：处理了不同React版本下useId生成的ID格式差异问题

使用建议

1. 直接在MDX文件中使用自定义组件，而非通过remark插件
2. 对于复杂图表，建议将内容以字符串形式传入
3. 注意处理换行符，确保图表定义格式正确
4. 在生产环境中添加适当的错误边界处理

总结

通过自定义Mermaid组件的方式，我们不仅解决了原有库的渲染问题，还获得了更灵活的配置能力和更好的错误处理机制。这种方案适用于大多数基于Fumadocs构建的文档系统，能够稳定地呈现各种Mermaid图表。

对于开发者而言，理解这类问题的本质在于DOM变化与渲染机制的匹配，有助于在遇到类似问题时快速定位和解决。自定义组件虽然增加了少量代码量，但带来了更好的可控性和稳定性，是值得推荐的解决方案。