用途:在 React 中构建 3D 场景、实现游戏循环、处理 3D 交互、优化 Three.js 渲染、加载资源和管理游戏状态时适用。
主要能力与规则:以声明式 @react-three/fiber JSX 为主,而非命令式 Three.js;全面类型化,如 useRef<THREE.Mesh>(null)、类型化 props 与事件处理器;游戏循环用 useFrame((state, delta) => …),基于 delta 时间而非墙钟;Three.js 对象用 ref,不直接改 props;减少重渲染,60 Hz 更新走 ref 而非 useState;使用 Drei 辅助组件如 OrbitControls、useTexture、Html、Sparkles、Trail;网格事件用 onClick、onPointerOver,无需手动射线检测;卸载时释放几何体、材质、纹理、音频缓冲;超过 10 个相似对象用 InstancedMesh;目标 60 fps,帧时间 ≤ 16.67 ms,可用 React DevTools 与 Spector.js 分析;逻辑放 hooks、渲染放 JSX、状态放 React;useFrame 内不用 useState;可访问性支持键盘等价操作、prefers-reduced-motion、HUD 对比度;资源仅从可信来源加载,用户提供的 URL 需校验。
使用方式:按上述规则编写组件,例如带类型的交互对象配合 useFrame 旋转与浮动,卸载时 dispose 资源,并根据 prefers-reduced-motion 调整动画速度。
限制与反模式:避免 setInterval 做动画、在 useFrame 中 setState、未类型化 ref、忘记释放资源、未校验用户 URL 就加载纹理。校验清单包括 ref 类型化、动画用 useFrame+delta、无 useState 于 useFrame、资源释放、相似网格用 InstancedMesh、尊重 reduced-motion、资源 URL 校验、帧时间达标。