React使用npx gltfjsx渲染glb动画模型报错排查

修复npx gltfjsx model.glb触发Invalid hook call错误 #

• 禁止直接使用无版本锁定的npx gltfjsx命令，npx会拉取独立的最新版依赖包，极易出现多React副本、版本不匹配问题。先在项目本地安装兼容版本的依赖：
  • React18项目执行npm i gltfjsx @react-three/fiber @react-three/drei three --save-dev
  • React17项目执行npm i gltfjsx@6 @react-three/fiber@7 @react-three/drei@9 three@0.148 --save-dev
    安装完成后执行本地命令生成组件：./node_modules/.bin/gltfjsx public/model.glb -o src/components/Model.jsx
• 执行npm ls react检查项目依赖树，如果存在多份React副本，在package.json中根据包管理器添加配置强制统一React版本：npm用overrides字段、yarn/pnpm用resolutions字段，指定项目根目录安装的React版本，删除node_modules和lock文件后重新执行npm install。

修复手动编写组件时actions为空、页面仅显示背景无3D内容问题 #

该问题是Mixamo导出动画+React Three Fiber技术栈的高频问题，按以下顺序排查：

1. 修正Blender导出glb的配置
   • 打开Blender导入源模型，选中骨骼Armature对象，确认动画片段绑定在骨骼上而非网格对象上，姿态模式下动画可正常播放。
   • 导出glb时必须勾选蒙皮、骨骼、动画三个选项，关闭「压缩动画」「剥离未使用动画轨道」选项，不要开启Draco压缩（如果开启需要额外在useGLTF中配置Draco解析器，否则会加载失败）。
2. 修正useAnimations调用逻辑

   核心注意点：useAnimations必须同时接收useGLTF返回的完整animations数组、以及包裹模型的group引用，二者缺一不可，否则会返回空的actions对象。
   参考正确的Model组件写法：

   // src/components/Model.jsx
   import { useRef, useEffect } from 'react'
   import { useGLTF, useAnimations } from '@react-three/drei'
   
   export default function Model(props) {
     const groupRef = useRef(null)
     // 路径对应public目录下的文件，注意开头加/
     const { scene, animations } = useGLTF('/model.glb')
     const { actions } = useAnimations(animations, groupRef)
   
     useEffect(() => {
       // 先打印所有可用动画名，不要硬编码动画名，避免拼写/导出名称不匹配
       console.log('可用动画列表：', Object.keys(actions))
       const targetAction = actions['Armature|mixamo.com|Layer0']
       if (targetAction) {
         targetAction.reset().fadeIn(0.3).play()
       }
   
       return () => {
         if (targetAction) targetAction.fadeOut(0.3)
       }
     }, [actions])
   
     return (
       <group ref={groupRef} {...props} dispose={null}>
         <primitive object={scene} />
       </group>
     )
   }
   
   // 预加载模型避免首帧卡顿
   useGLTF.preload('/model.glb')
   

3. 修正Canvas组件配置
   • 所有R3F生态组件（包括OrbitControls、光照、Suspense）必须放在Canvas组件内部，不能放在Canvas外层。
   • 检查模型初始位置是否在相机视锥内，可先给Model组件设置position={[0, -1, 0]}调整坐标，避免模型在相机视野外导致看不到内容。
     参考正确的Avatar组件写法：

   // src/components/Avatar.jsx
   import { Suspense } from 'react'
   import { Canvas } from '@react-three/fiber'
   import { OrbitControls } from '@react-three/drei'
   import Model from './Model'
   
   export default function Avatar() {
     return (
       <Canvas
         camera={{ position: [0, 1, 3], fov: 50 }}
         style={{ width: '100%', height: '100vh', background: '#eee' }}
       >
         <ambientLight intensity={0.6} />
         <directionalLight position={[2, 5, 2]} intensity={1} />
         <Suspense fallback={null}>
           <Model />
           <OrbitControls enableDamping />
         </Suspense>
       </Canvas>
     )
   }
   

4. 版本兼容校验
   三个核心依赖版本差过大也会导致动画解析失败，推荐对齐以下版本组合：
   • React18：three@0.158.0 + @react-three/fiber@8.15.12 + @react-three/drei@9.88.17
   • React17：three@0.148.0 + @react-three/fiber@7.0.26 + @react-three/drei@9.47.1

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