用 Three.js/R3F 做 3D 动效时如何保证…

在网页中构建实时 3D 场景、GLTF 动画、滚动联动相机、实例化渲染与 React Three Fiber 动效，并做好性能优化与 GPU 资源释放。

适用场景

解决思路

1. 用最小场景 + 渲染循环起步：创建 Scene、PerspectiveCamera(50, innerWidth/innerHeight, 0.1, 100)、WebGLRenderer({antialias:true})，setSize 后调用 renderer.setPixelRatio(Math.min(devicePixelRatio, 2)) 限制 DPR，把 renderer.domElement 挂到 body。
2. 用 renderer.setAnimationLoop 代替裸 requestAnimationFrame（兼容 WebXR，标签页失焦时自动暂停），并在循环里用 clock.getDelta() 得到 dt，把所有运动速率乘以 dt 以保证帧率无关。
3. 监听 resize：更新 camera.aspect、调用 camera.updateProjectionMatrix()、再 renderer.setSize。
4. 播放 GLTF 动画：用 GLTFLoader 加载模型，创建 THREE.AnimationMixer(gltf.scene)，对 gltf.animations 逐个 mixer.clipAction(clip) 存入 actions，播放 actions['Idle']?.play()，并在每帧循环里 mixer.update(dt)。
5. 交叉淡入淡出两个动画片段：to.reset().setEffectiveWeight(1).play(); from.crossFadeTo(to, dur, false)（warping=false 表示线性权重过渡）。
6. 一次性动画（如跳跃）：设置 action.setLoop(THREE.LoopOnce) 和 action.clampWhenFinished = true，并监听 mixer.addEventListener('finished', ...)。
7. 相机平滑跟随用指数插值阻尼：current.lerp(goal, 1 - Math.exp(-lambda * dt))，lambda 取 3~8，然后 camera.lookAt(0,0,0)。
8. 滚动联动相机：在 scroll 事件里计算 p = scrollY / (document.body.scrollHeight - innerHeight)（0→1），把 p 映射到相机目标位置，再由阻尼平滑过渡；曲线飞行路径用 THREE.CatmullRomCurve3 配合 curve.getPointAt(p)。
9. 大量相同物体用 InstancedMesh 一次 draw call 渲染：创建 InstancedMesh(geo, mat, count)，用 dummy Object3D 设置每个实例的 position 后 updateMatrix()，再 inst.setMatrixAt(i, dummy.matrix)，最后 inst.instanceMatrix.needsUpdate = true。
10. 每帧更新实例时设置 inst.instanceMatrix.setUsage(THREE.DynamicDrawUsage)；每实例颜色用 inst.setColorAt(i, color) 后设 inst.instanceColor.needsUpdate = true。
11. React Three Fiber 中用 useFrame((state, delta) => {...}) 驱动动画（用 delta 做帧率无关运动，用 state.clock.elapsedTime 做周期运动），Canvas 上设 dpr={[1, 2]} 限制像素比；模型用 drei 的 useGLTF 加载、useAnimations 播放动画，弹簧用 @react-spring/three，滚动用 drei 的 ScrollControls + useScroll。
12. 性能优化：限制像素比 Math.min(devicePixelRatio, 2)（retina/移动端最大收益）；复用 geometry 和 material；静态几何用 BufferGeometryUtils.mergeGeometries 合并；优先用 matcap 或烘焙光照而非多个实时光源（每个投影光源都很贵）；用材质/自发光动画（脉冲 emissive、位移）代替移动大量几何体。
13. 理解 GPU 资源释放边界：需要 dispose 的是 geometry.dispose()（VBO）、material.dispose()（着色器程序，但不含其纹理）、每个纹理槽的 texture.dispose()（map、normalMap、roughnessMap、envMap 等）、renderTarget.dispose()，最终销毁时 renderer.dispose() + renderer.forceContextLoss()；不需要 dispose 的是 Mesh/Group/Scene（移除后由 GC 回收）、Vector3/Matrix4/Color 等纯 JS 对象、灯光和相机（阴影贴图 render target 除外）。
14. 注意 scene.remove(mesh) 只是从场景图分离，不会释放任何 GPU 资源，geometry/material/texture 会一直驻留直到显式 dispose。
15. 写 disposeObject(root) 遍历销毁：root.traverse 中对 obj.geometry 调 dispose；对 obj.material 先判断是否为数组，逐个材质遍历其所有属性，遇到 v.isTexture 就 v.dispose()，最后 m.dispose()；完成后 root.parent?.remove(root)。
16. SPA 路由卸载时：renderer.setAnimationLoop(null); disposeObject(scene); renderer.dispose(); renderer.forceContextLoss?.()。
17. R3F 中 JSX 声明式创建的资源在卸载时会自动 dispose；泄漏来自命令式资源（在 hooks/refs/loader 里 new THREE.X()）。这类资源用 useMemo 创建，并在配对的 useEffect 清理函数中 dispose：useEffect(() => () => geometry.dispose(), [geometry])（依赖变化和卸载时都会释放）。
18. 跨多次挂载复用的共享资源，在 JSX 上设 dispose={null}，只在应用关闭时统一 dispose。
19. 用 renderer.info.memory（R3F 中用 useThree().gl.info.memory）验证泄漏：反复挂载/卸载 10 次，若 geometries/textures 不回到基线说明有泄漏。
20. 交付自包含 3D 场景时输出单个 HTML 文件：用 importmap 把 three 和 three/addons 指向 CDN，场景和渲染循环写在同一个内联 <script type="module"> 中，无需构建步骤。
21. 所有运动由单一时间源驱动：clock.getElapsedTime()（mixer 和相机都从它读取），不要用 Date.now() 或各对象自己的墙钟时间；随机性（实例位置、抖动）用固定种子以保证可复现。
22. 实现 ?t=N 定格截图工具：把场景状态写成 elapsed 的纯函数 frame(elapsed)（如 mesh.rotation.y = elapsed * 0.5；mixer 用 mixer.setTime(elapsed) 绝对时间而非 delta），若 URL 参数 t 存在就 frame(parseFloat(t)) 渲染一帧并设 window.__ready = true，否则用 setAnimationLoop(() => frame(clock.getElapsedTime()))。
23. 验证循环：在起始、中间、结束三个时刻（?t=0、?t=<mid>、?t=<end>）打开文件并截图，检查保真度（符合需求）和瑕疵（黑屏=解析/初始化错误查控制台、几何被裁剪/出框、NaN 位置导致物体消失、CDN 404 导致模型/纹理缺失）；用 npx playwright screenshot --wait-for-timeout=600 "file://$PWD/scene.html?t=1.5" frame-mid.png 截图。
24. 完成前检查：canvas 确实渲染（非空白、无控制台/WebGL 错误、无 CDN 404）；?t=N 能定格可复现帧（同一 N 得到相同像素、随机已播种）；已截取起始/中间/结束三帧且无裁剪/NaN/黑屏；若嵌入 SPA 已 dispose 且无泄漏（setAnimationLoop(null) + dispose）；已尊重 prefers-reduced-motion（在相关处减慢或停止旋转/自动播放）。

适用边界 · 注意事项

• 只需要静态 3D 展示、无动画或交互时，不必引入完整渲染循环与动画系统。
• 场景简单到单个 HTML 文件即可完成时，不要引入打包器（bundler）。
• 没有 GPU 上下文的环境无法运行 WebGL（无头验证需用 Playwright/Chromium 提供的 swiftshader）。