r3f-loaders

React Three Fiber 加载器

首先检查已安装的 Fiber、Drei、Three.js 和 React 版本。示例使用 Fiber 9 / React 19。请确认实际的资源路径、节点名称、格式和压缩方式；不要臆测模型的结构。

加载并复用模型

在 Canvas 下方挂载。在应用中提供 /models/robot.glb。这些克隆拥有独立的对象变换，但会有意共享缓存的几何体和材质。

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>
  )
}

加载决策

• 对于 glTF/GLB，优先使用 useGLTF；对于其他格式，使用搭配相应 Three.js 加载器的 useLoader。Fiber 9 还支持使用外部持有的加载器实例，以便隔离配置。
• 加载器 Hook 会挂起组件。对需要一起显示的资源设置边界；对独立加载的资源使用不同边界。在交互前预加载可能需要的资源，而不是整个目录。
• 预加载会启动请求，但不保证资源能立即显示，也不保证 GPU 着色器能立即编译。资源解码和首次渲染仍可能耗时。
• 条件加载意味着有条件地挂载调用该 Hook 的子组件。不要将 null 当作伪 URL 传入，也不要有条件地调用 Hook。
• Three.js 附加模块使用 three/addons/loaders/GLTFLoader.js 这类路径。请检查已安装的导出项中是否有重命名的加载器；现代 Three.js 使用 HDRLoader，而较早的示例使用 RGBELoader。
• 在需要公开具名节点/材质时，可使用带类型的 gltfjsx，并检查生成的结果。对于包装组件，请使用 ThreeElements['group']，而不是已移除的全局 JSX 类型命名空间。

缓存、克隆和生命周期

• 将缓存的加载器结果视为共享资源。将同一个 Object3D 挂载到两个父级下时，它会在两者之间移动；重复放置时请克隆对象图。
• Drei Clone 支持普通对象图复制和骨架感知克隆。对于独立的动画混合器，使用稳定的 SkeletonUtils.clone 根节点，能明确所有权。
• 对象图克隆通常会共享几何体、纹理和材质。需要对单个实例进行编辑时，请克隆相应的材质/纹理；深度克隆所有内容会浪费内存。
• 防止单个使用方释放共享的缓存资源（在共享子树上设置 dispose={null}）。只有在所有使用方都已卸载后，应用的缓存所有者才能释放这些资源。
• R3F 不会自动释放原语。useGLTF.clear(url) 和 useLoader.clear(...) 都不是完整的 GPU 清理操作。
• 不要在渲染期间清除缓存，也不要将修改缓存场景的变换/材质作为本地设置的捷径。

解码器和失败处理

• useGLTF 集成了 Draco/Meshopt 支持，但解码器 URL 和加载器配置必须与资源及托管策略相匹配。对于 KTX2 纹理，请在加载前配置带有渲染器能力检测的 KTX2Loader。
• 预加载和实际加载必须使用相同的加载器/解码器设置。请在请求开始前完成配置；之后的更改不会让已缓存的结果重新解析。
• 避免在每次渲染或加载回调中创建新的解码器 Worker 池。请为自定义加载器/解码器实例指定明确的所有者，并负责清理。
• Suspense 处理的是待完成的工作，不处理被拒绝的请求。请使用错误边界，并明确制定重试/重新挂载策略；重试时清除缓存应由用户操作或受控的恢复流程负责。
• 在 Canvas 内部，使用 Three.js 回退界面或 Drei Html。Drei Loader 是 DOM 覆盖层，应放在 Canvas 外部。
• useProgress 反映的是加载管理器的活动状态，不一定能准确反映单个资源的字节级完成情况。不要把不可用的 Content-Length 当作可靠的分母。
• 请测试网络错误、CORS、解码器/转码器托管，以及实际的压缩资源。未经压缩的 GLB 冒烟测试无法验证所有解码器路径。

Sources

• Fiber useLoader, Drei useGLTF, Clone.
• GLTFLoader, KTX2Loader, SkeletonUtils.