threejs-r3f

Three.js / React Three Fiber

使用 R3F v9（React 19）和 pmndrs 生态构建 3D 网页体验的指南。

版本约束

软件包	版本	React
@react-three/fiber	v9.x	19.x
@react-three/drei	v9.x+	19.x
@react-three/rapier	v2.x	19.x
three	r171+	—

React 18 项目请使用 fiber v8 + rapier v1。切勿混用不同版本系列。

---

安装

独立的 Vite + R3F 应用

bun create vite my-scene -- --template react-ts
cd my-scene
bun add three @react-three/fiber @react-three/drei
bun add -d @types/three
bun dev

添加到现有 React 19 项目

bun add three @react-three/fiber @react-three/drei
bun add -d @types/three

可选软件包：bun add @react-three/rapier（物理效果）、bun add zustand（状态管理）、bun add leva（调试 GUI）。

---

场景设置

如需了解最简场景模板、Canvas 属性表、frameloop 值、响应式 Canvas 和 WebGPU 渲染器引导，请阅读 references/scene-setup.md。

无需阅读参考文档也应牢记以下要点：

• Canvas 默认值：antialias: true、outputColorSpace = SRGBColorSpace、toneMapping = ACESFilmicToneMapping、ColorManagement.enabled = true
• 始终设置 dpr={[1, 2]}，以限制设备像素比
• 使用 shadows="soft" 启用阴影贴图；为网格添加 castShadow/receiveShadow
• 对仅需在交互时重新渲染的静态场景，使用 frameloop="demand"

---

Drei 助手 — 前 15 个

所有内容均从 @react-three/drei 导入。完整清单、属性和示例请阅读 references/drei-helpers.md。

控制

• OrbitControls — 旋转/缩放/平移；添加 makeDefault 以便通过 useThree 访问
• ScrollControls — 由滚动驱动的场景；与 useFrame 中的 useScroll 配合使用
• PresentationControls — 带弹簧动画的拖动；无需 OrbitControls
• KeyboardControls — 有类型的按键状态上下文；在 useFrame 中通过 get() 命令式读取

场景布置

• Environment — 使用预设（'sunset' | 'warehouse' | 'city' | ...）或自定义 HDR 实现 IBL
• Stage — 单组件场景布置：照明、相机适配、阴影
• ContactShadows — 在平面上模拟柔和阴影；比阴影贴图更省资源
• Float — 为主视觉对象添加漂浮/上下浮动的空闲动画

形状 / 内容

• Text — 支持字体加载、自动换行和轮廓的 SDF 3D 文本
• Html — 在 3D 场景中嵌入 DOM 内容；支持 occlude 和 transform

加载器

• useGLTF — 加载并缓存 GLTF/GLB；自动配置 Draco CDN 解码器
• useTexture — 加载并缓存纹理；对象形式可用于 PBR 贴图

性能

• Instances / Instance — 使用简单的组件 API 创建实例化网格
• Detailed — LOD：根据相机距离显示不同网格
• PerformanceMonitor — FPS 回调；与 AdaptiveDpr 配合使用

材质

• MeshTransmissionMaterial — 带折射和色差的物理材质玻璃

---

资源管线

GLTF 加载

import { useGLTF } from '@react-three/drei'
import { Suspense } from 'react'

function Model(props) {
  const { nodes, materials } = useGLTF('/model.glb')
  return (
    <group {...props} dispose={null}>
      <mesh geometry={nodes.Body.geometry} material={materials.Metal} castShadow />
    </group>
  )
}

useGLTF.preload('/model.glb')

// Wrap in Suspense
<Canvas>
  <Suspense fallback={null}>
    <Model />
  </Suspense>
</Canvas>

gltfjsx CLI

# Generate TypeScript component + Draco-compress the GLB
npx gltfjsx model.glb --transform --types --shadows
# Outputs: model-transformed.glb (move to /public) + Model.tsx (move to /src/components)

--transform 通过 Draco 几何压缩、将纹理缩小到 1024px 并转换为 WebP，可将大多数模型缩小 70–90%。

有关克隆模式、KTX2 纹理、延迟加载和并行预加载，请阅读 references/r3f-patterns.md。

---

性能规则

绘制调用预算：

• 移动设备：< 100 次绘制调用
• 桌面设备：< 300 次绘制调用

7 个反模式——绝对不要这样做：

1. 绝不要在 useFrame 中调用 setState——直接修改 ref
2. 动画始终使用 delta——绝不要使用固定增量
3. 绝不要在 onPointerMove 中调用 setState——直接修改 ref
4. 绝不要在 useFrame 中读取响应式 store 状态——使用 store.getState() 命令式形式
5. 绝不要在渲染循环中有条件地挂载或卸载——改用 visible 属性
6. 绝不要在 useFrame 中创建 new THREE.Vector3()——在外部创建，并使用 .set() 复用
7. 绝不要为相同网格创建重复的几何体或材质——通过 useMemo 或 Instances 共享

释放资源： 对动态创建的 Three.js 对象，始终在 useEffect 清理函数中调用 geometry.dispose() 和 material.dispose()。

阅读 references/performance.md，了解全部 7 个反模式及错误/正确代码示例、纹理优化、视锥剔除、统计工具和移动设备规则。

---

状态、物理、调试 GUI 和 WebGPU

关于这些主题，请阅读 references/extras.md：

• Zustand 命令式模式（确保 useFrame 正确运行的必要条件）
• Leva 调试 GUI 设置
• Rapier 物理快速入门
• WebGPU 渲染器引导设置

关于完整的 Rapier v2 API（所有碰撞体类型、碰撞事件、传感器、关节、力、InstancedRigidBodies），请阅读 references/physics.md。

---

参考文件

• references/scene-setup.md — 最简场景模板、Canvas 默认值、frameloop、响应式 Canvas、WebGPU 渲染器
• references/r3f-patterns.md — Canvas 属性、useFrame、useThree、事件系统、滚动驱动场景、GLTF 克隆模式、KTX2、延迟加载
• references/drei-helpers.md — 按类别整理的完整 Drei 清单：每个辅助工具的导入方式、关键属性和示例
• references/performance.md — 全部 7 个反模式及错误/正确代码示例、实例化、LOD、纹理压缩、资源释放检查清单、移动设备规则
• references/physics.md — 完整的 Rapier v2：碰撞体、碰撞事件、传感器、6 种关节、力/冲量、InstancedRigidBodies
• references/extras.md — Zustand 命令式模式、Leva 调试 GUI、Rapier 快速入门、WebGPU 引导设置