React动态渲染Mermaid图表报错：Cannot read properties of undefined (reading 'createElementNS')

这个错误不是React或Mermaid的版本问题，核心原因是代码手动操作DOM时和Mermaid的渲染流程冲突，加上不合理的API调用导致的。下面是具体分析和修复方案：

问题根源 #

1. 错误调用mermaid.contentLoaded()：这个方法是Mermaid用于自动扫描页面所有.mermaid元素并批量渲染的，手动调用会触发Mermaid重新扫描DOM，此时组件DOM可能未完全就绪或已被React更新，进而引发createElementNS未定义错误。
2. 固定ID导致DOM冲突：如果页面存在多个Mermaid组件实例，重复的ID会让DOM获取逻辑混乱，触发渲染异常。
3. 状态未同步props变化：用useState接收props.chart但未监听props更新，父组件修改图表代码时，子组件无法同步更新。

修复方案 #

方案一：修正手动渲染逻辑（不依赖官方React组件）

import React, { useEffect, useRef } from 'react';
import mermaid from 'mermaid';

// 全局只初始化一次Mermaid
if (!mermaid.isInitialized) {
  mermaid.initialize({
    startOnLoad: false, // 关闭自动加载，手动控制渲染节奏
    securityLevel: 'loose',
    fontFamily: 'monospace',
    logLevel: 5
  });
  mermaid.isInitialized = true;
}

const Mermaid = ({ chart }) => {
  const mermaidRef = useRef(null);

  useEffect(() => {
    const container = mermaidRef.current;
    if (!container || !chart) return;

    // 清空容器后重新渲染
    container.innerHTML = '';
    // 用唯一标识避免渲染冲突
    mermaid.render(`mermaid-${Date.now()}`, chart, (svgCode) => {
      container.innerHTML = svgCode;
    });
  }, [chart]);

  return <div ref={mermaidRef} className="mermaid"></div>;
};

export default Mermaid;

方案二：使用Mermaid官方React组件（更简洁可靠）

直接用官方维护的@mermaid-js/mermaid-react包，彻底避免手动操作DOM的问题：

1. 安装依赖：

npm install @mermaid-js/mermaid-react

2. 组件使用示例：

import React from 'react';
import { Mermaid } from '@mermaid-js/mermaid-react';

const CustomMermaidChart = ({ chart }) => {
  return (
    <Mermaid
      chart={chart}
      options={{
        securityLevel: 'loose',
        fontFamily: 'monospace',
        logLevel: 5
      }}
    />
  );
};

export default CustomMermaidChart;

关键修复点说明 #

• 关闭startOnLoad: false：避免Mermaid自动扫描DOM和手动渲染逻辑冲突。
• 用useRef替代getElementById：确保精准获取当前组件的DOM元素，避免多实例ID冲突。
• 移除mermaid.contentLoaded()：手动渲染场景下不需要调用这个自动加载方法。
• 监听props.chart变化：保证父组件更新图表代码时，子组件同步重新渲染。

内容的提问来源于stack exchange，提问作者nidhi mishra