React集成three.js添加3D模型报react-three-fiber模块未找到错误

报错由两个问题共同导致：

• 项目本地未安装react-three-fiber相关依赖
• 参考的教程版本过旧，旧版react-three-fiber包已停止维护，目前官方包已迁移至@react-three/fiber命名空间，直接安装旧包大概率会和新版React产生版本兼容问题。
  另外原示例代码存在层级错误：OrbitControls控件不应该放在mesh标签内部，需要和模型、光源保持同级，否则控件无法正常生效。

1. 安装正确版本的依赖 #

在项目根目录打开终端，执行对应包管理工具的安装命令：

• npm 环境执行：
  npm install three @react-three/fiber @react-three/drei
• yarn 环境执行：
  yarn add three @react-three/fiber @react-three/drei

说明：@react-three/drei是R3F生态官方维护的通用组件库，封装了OrbitControls、模型加载器等常用能力，无需手动extend注册，能大幅降低兼容问题出现概率。

2. 替换Model.jsx代码适配新版API #

将原有Model.jsx的代码替换为以下适配新版依赖的版本，外层容器直接复用原有头像区域的me类名，无需额外修改原有CSS：

import React, { useRef, Suspense } from "react";
import { Canvas, useFrame } from "@react-three/fiber";
import { OrbitControls, useGLTF } from "@react-three/drei";

// 测试用旋转立方体，确认环境正常后可替换为自己的3D头像
function RotatingTestBox() {
  const meshRef = useRef();
  useFrame(() => {
    meshRef.current.rotation.y += 0.01;
    meshRef.current.rotation.x += 0.005;
  })
  return (
    <mesh ref={meshRef}>
      <boxGeometry args={[1.5, 1.5, 1.5]} />
      <meshStandardMaterial color="#ffffff" wireframe />
    </mesh>
  )
}

// 3D头像组件，GLB模型放public目录后可直接使用
function AvatarModel(props) {
  // 路径替换为自己的3D头像文件路径
  const { scene } = useGLTF("/virtual-avatar.glb");
  return <primitive object={scene} {...props} />
}

function Model() {
  return (
    <div className="me">
      <Canvas camera={{ position: [0, 0, 3], fov: 50 }}>
        {/* 场景光源，缺失会导致模型发黑看不见 */}
        <ambientLight intensity={0.8} />
        <directionalLight position={[2, 2, 2]} intensity={1} />
        {/* 轨道控制器配置：自动旋转、禁止缩放平移、限制俯仰角度避免穿模 */}
        <OrbitControls 
          autoRotate 
          autoRotateSpeed={2}
          enableZoom={false}
          enablePan={false}
          minPolarAngle={Math.PI/3}
          maxPolarAngle={Math.PI/1.5}
        />
        {/* 环境验证阶段先打开下面这行立方体代码，关闭头像组件代码 */}
        <RotatingTestBox />
        {/* 立方体正常渲染后，注释上面的测试组件，打开下面的头像代码即可加载自己的模型 */}
        {/* <Suspense fallback={null}>
          <AvatarModel scale={2} position={[0, -1, 0]} />
        </Suspense> */}
      </Canvas>
    </div>
  );
}

export default Model;

3. 加载自定义3D虚拟头像 #

等编译通过、页面上能正常显示自动旋转的白色线框立方体，说明3D环境已经配置完成，后续替换自己的头像即可：

• 将导出为GLB/GLTF格式的3D虚拟头像文件放入项目public目录
• 注释代码里的RotatingTestBox组件，取消AvatarModel相关代码的注释
• 微调AvatarModel的scale、position参数，直到头像的大小、位置符合页面设计要求即可。

• 如果安装依赖后依然提示模块找不到，删除项目根目录下的node_modules文件夹和锁文件（package-lock.json/yarn.lock），重新执行依赖安装命令后重启开发服务即可。
• 如果画布区域空白不显示内容，给.me类设置明确的宽高值（和你原来放个人照片的容器尺寸保持一致即可），Canvas会自动撑满父容器。
• 如果模型显示纯黑，检查是否添加了环境光和平行光组件，3D场景无光源时无法显示正常材质效果。

内容的提问来源于stack exchange，提问作者Somdotta Sarkar