在 React Three Fiber 中加载、复用与排错…

在 React Three Fiber 项目中加载 glTF/GLB 或其他 Three.js 支持的 3D 资产，并处理缓存、克隆、预加载、解码器以及加载/错误 UI。

适用场景

解决思路

1. 先检查已安装的 Fiber、Drei、Three.js 和 React 版本；示例使用 Fiber 9 / React 19。核对实际资产路径、节点名、格式和压缩方式，不要臆造模型结构。
2. 在 Canvas 下方挂载加载组件；在应用中提供 `/models/robot.glb`。这些克隆具有独立的 object transforms，但会有意共享缓存的 geometry/materials。
3. 按以下结构加载并复用模型： ```tsx import { Suspense } from 'react' import { Clone, useGLTF } from '@react-three/drei' function Models() { const { scene } = useGLTF('/models/robot.glb') return ( <group dispose={null}> <Clone object={scene} position={[-1.2, 0, 0]} /> <Clone object={scene} position={[1.2, 0, 0]} /> </group> ) } export default function Example() { return ( <Suspense fallback={null}> <Models /> </Suspense> ) } ```
4. 对 glTF/GLB 优先使用 `useGLTF`；对其他格式使用 `useLoader` 搭配对应的 Three.js loader。Fiber 9 也接受外部拥有的 loader 实例，用于需要配置隔离的场景。
5. Loader hooks 会 suspend。把应一起显示的资产放在同一个 boundary；独立加载的资产使用分开的 boundary。提前预加载交互中可能需要的资产，而不是整个目录。
6. 预加载只是发起请求；不保证即时显示，也不保证 GPU shader 编译完成。资产解码和首次渲染仍可能耗时。
7. 条件加载的做法是条件挂载一个调用 hook 的子组件。不要把 `null` 当作伪 URL 传入，也不要条件调用 hook。
8. Three.js addons 使用诸如 `three/addons/loaders/GLTFLoader.js` 的路径。检查已安装导出中是否有重命名的 loader；现代 Three.js 在旧示例使用 `RGBELoader` 的地方使用 `HDRLoader`。
9. 当需要暴露命名节点/材质时，使用带类型的 gltfjsx，并检查生成结果。对 wrapper 使用 `ThreeElements['group']`，不要使用已移除的全局 JSX 类型命名空间。
10. 把缓存 loader 结果视为共享资源。把一个 Object3D 挂到两个父级下会在父级间移动它；重复放置时要克隆整个 graph。
11. Drei Clone 支持普通 graph 复制和 skeleton-aware 克隆。若需要独立 animation mixers，使用稳定的 `SkeletonUtils.clone` 根节点可让所有权更明确。
12. graph 克隆通常共享 geometry、textures 和 materials。做 per-instance 编辑前克隆特定 material/texture；深克隆所有内容会浪费内存。
13. 阻止单个消费者释放共享缓存资源（在共享子树上使用 `dispose={null}`）。应用级缓存拥有者只能在所有消费者都消失后释放它们。
14. Primitives 不会被 R3F 自动 dispose。`useGLTF.clear(url)` 和 `useLoader.clear(...)` 都不是完整的 GPU 清理操作。
15. 不要在 render 期间清空缓存，也不要把修改缓存 scene 的 transforms/materials 当作局部 setup 捷径。
16. `useGLTF` 集成了 Draco/Meshopt 支持，但 decoder URL 和 loader 配置必须匹配资产与托管策略。对于 KTX2 textures，在加载前配置带 renderer capability detection 的 KTX2Loader。
17. 预加载和实际加载使用相同的 loader/decoder 设置。在请求开始前配置；之后的更改不会追溯重新解析已缓存结果。
18. 避免在每次 render 或 load callback 中创建新的 decoder worker pool。给自定义 loader/decoder 实例一个明确的所有者和清理逻辑。
19. Suspense 处理 pending work，不处理 rejected requests。使用 error boundary 并配合明确的 retry/remount 策略；用于重试的 cache eviction 应放在用户操作或受控恢复路径中。
20. 在 Canvas 内部使用 Three.js fallback 或 Drei Html。Drei Loader 是 DOM overlay，应放在 Canvas 外部。
21. `useProgress` 反映 loading manager 的活动，不一定代表单个资产的字节级精确完成。避免把不可用的 Content-Length 当作可信分母。
22. 测试 network errors、CORS、decoder/transcoder hosting 和实际压缩资产。未压缩 GLB 的冒烟测试不能验证所有 decoder 路径。

适用边界 · 注意事项

• 不适用于非 React Three Fiber / React Three.js 项目，或未安装对应 Fiber、Drei、Three.js、React 版本时。
• 资产格式不是 glTF/GLB 且没有匹配的 Three.js loader/decoder 与托管配置时，不要用 useGLTF 硬套。
• 需要保证预加载即时显示、把 Drei Loader 放进 Canvas，或依赖 Content-Length 做字节级精确进度时，本技能不适用。