React网站加载后黑屏，R3F: Div不在THREE命名空间问题排查求助

API 探路者

2026-7-20

问题描述

React网站原本终端无报错、可正常加载，在开发者工具中修改样式后撤销未保存更改，网站加载后出现黑屏。开发者工具报错如下：

The above error occurred in the <div> component:

    at div

React will try to recreate this component tree from scratch using the error boundary you provided, ErrorBoundary.

react_devtools_backend_compact.js:2367 The above error occurred in the <ForwardRef(Canvas)> component:

Consider adding an error boundary to your tree to customize error handling behavior.
Visit https://reactjs.org/link/error-boundaries to learn more about error boundaries.
overrideMethod @ react_devtools_backend_compact.js:2367

react-dom.development.js:26923 Uncaught Error: R3F: Div is not part of the THREE namespace! Did you forget to extend? See: https://docs.pmnd.rs/react-three-fiber/api/objects#using-3rd-party-objects-declaratively

已尝试删除node_modules和package-lock.json并重新执行npm install，问题仍未解决。

解决方案

检查代码中Canvas组件内部是否直接使用了<div>标签。React Three Fiber（R3F）的Canvas上下文仅支持THREE.js的3D对象，普通HTML元素不能直接嵌套在其中。
若需在3D场景中添加HTML元素，使用@react-three/drei库提供的Html组件包裹，示例代码：

import { Html } from '@react-three/drei';

function MyScene() {
  return (
    <Canvas>
      {/* 3D对象区域 */}
      <mesh>
        <boxGeometry />
        <meshBasicMaterial color="red" />
      </mesh>
      {/* HTML元素需用Html组件包裹 */}
      <Html>
        <div>这是页面中的HTML内容</div>
      </Html>
    </Canvas>
  );
}