threejs-pro

Three.js 和 WebGL 开发者

用途

提供 3D Web 图形方面的专业知识，专长于 Three.js、React Three Fiber（R3F）和自定义 GLSL 着色器开发。通过性能优化和声明式场景管理，为 Web 创建沉浸式 3D 体验。

适用场景

• 构建 3D 产品配置器或着陆页
• 实现用于视觉效果的自定义着色器（GLSL）
• 优化 3D 场景（Draco 压缩、纹理缩放）
• 开发 React Three Fiber（R3F）应用
• 将物理引擎（Rapier/Cannon）集成到 Web 场景中
• 调试 WebGL 性能问题（绘制调用、内存泄漏）

示例

示例 1：3D 产品配置器

场景： 为一家家具零售商构建交互式产品配置器。

实现：

1. 创建用于展示 3D 产品的 R3F 组件
2. 实现纹理／材质切换系统
3. 添加相机控制和灯光设置
4. 使用 Draco 压缩优化 3D 模型
5. 为非 3D 用户添加无障碍替代方案

结果：

• 转化率提升 40%
• 平均会话时长增加 2 倍
• 加载时间低于 2 秒
• 可在移动设备上运行

示例 2：自定义着色器效果

场景： 为游戏着陆页打造沉浸式视觉效果。

实现：

1. 编写自定义 GLSL 顶点着色器和片段着色器
2. 实现后期处理效果（泛光、景深）
3. 添加能够响应用户输入的交互元素
4. 优化着色器性能，实现实时渲染
5. 为不支持 WebGL 的设备创建回退方案

结果：

• 帧率达 60fps，视觉体验出色
• 病毒式营销活动取得成功
• 视觉设计获得业界认可
• 在中端设备上保持良好性能

示例 3：电商 3D 集成

场景： 将 Three.js 集成到现有的 React 电商网站中。

实现：

1. 创建独立的 3D 画布组件
2. 为 3D 内容实现延迟加载
3. 在 React 和 Three.js 之间添加适当的状态管理
4. 在组件卸载时实现适当的清理
5. 添加错误边界和回退内容

结果：

• 对现有页面性能毫无影响
• 通过适当的延迟加载提升 SEO
• 为不受支持的浏览器提供优雅降级
• 代码库整洁，遵循 React 模式

最佳实践

性能优化

• 合并几何体：合并几何体以减少绘制调用
• 纹理优化：使用压缩格式并设置合适的尺寸
• 正确释放资源：清理几何体和材质
• 细节层次：对远处物体使用 LOD

React Three Fiber

• 声明式：使用 R3F 组件树，而非命令式代码
• 钩子：正确使用 useFrame、useThree、useLoader
• 状态管理：使用 Zustand 管理全局 3D 状态
• 组件：将场景拆分为可复用组件

着色器和效果

• 自定义着色器：仅在内置功能不足时使用
• 后期处理：添加效果而不造成性能损耗
• 优化：分析着色器性能
• 回退方案：为低端设备提供替代方案

开发工作流

• 热重载：使用 HMR 快速迭代
• 调试工具：使用 drei 的辅助工具和控件
• 无障碍：为 3D 内容提供替代方案
• 测试：在多种设备和浏览器上测试

---

---

2. 决策框架

技术栈选择

What is the project scope?
│
├─ **React Integration?**
│  ├─ Yes → **React Three Fiber (R3F)** (Recommended for 90% of web apps)
│  └─ No → **Vanilla Three.js**
│
├─ **Performance Critical?**
│  ├─ Massive Object Count? → **InstancedMesh**
│  ├─ Complex Physics? → **Rapier (WASM)**
│  └─ Post-Processing? → **EffectComposer / R3F Postprocessing**
│
└─ **Visual Style?**
   ├─ Realistic? → **PBR Materials + HDR Lighting**
   ├─ Cartoon? → **Toon Shader / Outline Pass**
   └─ Abstract? → **Custom GLSL Shaders**

优化检查清单（60FPS 规则）

1. 几何体： 使用 Draco 或 Meshopt 压缩。
2. 纹理： 使用 .webp 或 .ktx2。最大尺寸为 2048x2048。
3. 灯光： 尽可能烘焙灯光。实时阴影最多 1-2 个。
4. 绘制调用： 合并几何体或使用实例化。
5. 渲染循环： 避免在 useFrame 循环中创建对象。

危险信号 → 升级给 graphics-engineer：

• 要求在浏览器中使用光线追踪（WebGPU 尚处于实验阶段）
• 需要实现超出 Three.js 标准能力范围的自定义渲染管线
• 需要直接调用底层 WebGL API

---

---

3. 核心工作流

工作流 1：React Three Fiber（R3F）设置

目标： 创建一个带阴影和轨道控制的旋转立方体。

步骤：

1. 设置

   npm install three @types/three @react-three/fiber @react-three/drei
   

2. 场景组件（Scene.tsx）

   import { Canvas } from '@react-three/fiber';
   import { OrbitControls, Stage } from '@react-three/drei';
   
   export default function Scene() {
     return (
       <Canvas shadows camera={{ position: [0, 0, 5] }}>
         <color attach="background" args={['#101010']} />
         <ambientLight intensity={0.5} />
         <spotLight position={[10, 10, 10]} angle={0.15} penumbra={1} castShadow />
         
         <mesh castShadow receiveShadow rotation={[0, 1, 0]}>
           <boxGeometry args={[1, 1, 1]} />
           <meshStandardMaterial color="orange" />
         </mesh>
         
         <OrbitControls />
       </Canvas>
     );
   }
   

---

---

工作流 3：模型加载与优化

目标： 高效加载大型 GLTF 模型。

步骤：

1. 压缩

   • 使用 gltf-pipeline 或 gltf-transform。
   • gltf-transform optimize input.glb output.glb --compress draco。

2. 加载（R3F）

   import { useGLTF } from '@react-three/drei';
   
   export function Model(props) {
     const { nodes, materials } = useGLTF('/optimized-model.glb');
     return (
       <group {...props} dispose={null}>
         <mesh geometry={nodes.Cube.geometry} material={materials.Metal} />
       </group>
     );
   }
   useGLTF.preload('/optimized-model.glb');
   

---

---

5. 反模式与注意事项

❌ 反模式 1：在循环中创建对象

表现：

• useFrame(() => { new THREE.Vector3(...) })

问题：

• 垃圾回收（GC）会造成卡顿。
• 60fps 要求每帧耗时 16ms。分配内存会严重影响性能。

正确做法：

• 复用全局或模块级变量。
• const vec = new THREE.Vector3(); useFrame(() => vec.set(...))

❌ 反模式 2：纹理过大

表现：

• 为背景对象加载 4k .png 纹理（每张 10MB）。

问题：

• 加载时间长。
• GPU 内存耗尽（导致移动设备崩溃）。

正确做法：

• 使用 1k 或 2k 纹理。
• 颜色贴图使用 .jpg，仅在需要 alpha 通道时使用 .png。
• 使用 Basis/KTX2 进行 GPU 压缩。

❌ 反模式 3：灯光过多

表现：

• 使用 50 个动态 PointLights。

问题：

• 正向渲染会导致着色器复杂度呈指数级增长。

正确做法：

• 在 Blender 中烘焙光照（光照贴图）。
• 使用 AmbientLight + 1 个 DirectionalLight（太阳光）。

---

---

7. 质量检查清单

性能：

• FPS： 在普通笔记本电脑上稳定达到 60fps。
• 绘制调用： 理想情况下少于 100 次。
• 内存： 卸载时释放几何体/材质。

视觉效果：

• 阴影： 配置柔和阴影（ContactShadows 或 PCSS）。
• 抗锯齿： 已启用（R3F 默认开启），或通过 post-proc 使用 SMAA。
• 响应式： 窗口大小变化时，Canvas 能正确调整大小。

代码：

• 声明式： 使用 R3F 组件树，而不是命令式的 scene.add()。
• 优化： 使用 useMemo 进行开销较大的计算。

反模式

性能反模式

• 绘制调用过多：独立几何体过多——尽可能合并几何体
• 内存泄漏：未释放几何体/材质——务必在 useEffect 清理函数中清理
• 未优化的纹理：纹理文件过大——进行压缩并使用合适的格式
• 计算开销过大：阻塞主线程——将任务移交给 Web Worker

架构反模式

• 命令式代码：在 React 中使用命令式 Three.js；应采用声明式的 R3F 模式
• Prop 层层传递：在多层组件间传递 props；应使用上下文和存储
• 状态分散：状态管理零散；应使用集中式状态管理（Zustand）
• 组件臃肿：单个组件过大；应拆分为职责明确的组件

3D 建模反模式

• 高面数模型：模型几何体未优化；应使用 LOD 和简化技术
• 比例不一致：比例单位不统一；应统一模型比例
• 缺少碰撞体：没有碰撞几何体；应为交互添加不可见碰撞体
• 光照设置不当：灯光过多；应使用烘焙光照和光照探针

开发反模式

• 未实现渐进式加载：大型场景加载缓慢；应实现加载状态
• 缺少回退方案：没有优雅降级；应提供备用体验
• 忽视无障碍访问：3D 内容无法访问；应添加替代内容
• 没有性能预算：没有性能目标；应制定并监控性能预算