构建交互式 Three.js WebGL/WebGPU…

在浏览器中开发交互式 3D 场景、产品配置器、3D 可视化或沉浸式 Web 体验时，用 Three.js 组织场景、相机、渲染器、材质、灯光、动画与性能优化。

适用场景

解决思路

1. 构建基础场景：用 `import * as THREE from 'three';` 和 `import { OrbitControls } from 'three/addons/controls/OrbitControls.js';`；创建 `THREE.Scene()` 并设置 `scene.background = new THREE.Color(0x333333)`；创建 `THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000)` 并设置 `camera.position.set(0, 2, 5)`；创建 `THREE.WebGLRenderer({ antialias: true })`，设置 `renderer.setSize(window.innerWidth, window.innerHeight)`、`renderer.setPixelRatio(window.devicePixelRatio)`、`renderer.shadowMap.enabled = true`，并 `document.body.appendChild(renderer.domElement)`；添加 `THREE.AmbientLight(0xffffff, 0.5)` 和 `THREE.DirectionalLight(0xffffff, 1)`，设置 `directionalLight.position.set(5, 10, 7.5)`、`directionalLight.castShadow = true`；创建 `OrbitControls(camera, renderer.domElement)`，设置 `controls.enableDamping = true`、`controls.dampingFactor = 0.05`；在 `animate` 中用 `requestAnimationFrame(animate)`、`controls.update()`、`renderer.render(scene, camera)`；监听 `resize`，更新 `camera.aspect`、`camera.updateProjectionMatrix()`、`renderer.setSize(window.innerWidth, window.innerHeight)`。
2. 配置 WebGPU：用 `import * as THREE from 'three/webgpu';`；创建 `THREE.WebGPURenderer({ antialias: true })`，设置 `renderer.setPixelRatio(window.devicePixelRatio)`、`renderer.setSize(window.innerWidth, window.innerHeight)`、`renderer.setAnimationLoop(animate)`、`renderer.toneMapping = THREE.LinearToneMapping`、`renderer.toneMappingExposure = 1`，并 `document.body.appendChild(renderer.domElement)`。
3. 创建带材质的 Mesh：用 `new THREE.BoxGeometry(1, 1, 1)`；用 `new THREE.MeshStandardMaterial({ color: 0x00ff00, roughness: 0.5, metalness: 0.5 })`；用 `new THREE.Mesh(geometry, material)` 并 `scene.add(cube)`。
4. 创建带纹理的 Mesh：用 `new THREE.TextureLoader()` 的 `.load('texture.jpg')` 加载纹理；设置 `texture.colorSpace = THREE.SRGBColorSpace`；用 `new THREE.MeshStandardMaterial({ map: texture })` 创建材质；用 `new THREE.Mesh(geometry, texturedMaterial)` 并 `scene.add(mesh)`。
5. 实现三点布光：添加 keyLight 为 `new THREE.DirectionalLight(0xffffff, 3)`，设置位置 `(5, 10, 7.5)` 并 `castShadow = true`；添加 fillLight 为 `new THREE.DirectionalLight(0xffffff, 1)`，设置位置 `(-5, 5, -5)`；添加 rimLight 为 `new THREE.DirectionalLight(0xffffff, 0.5)`，设置位置 `(0, 5, -10)`；添加 ambient 为 `new THREE.AmbientLight(0x404040, 0.5)`。
6. 配置物理光与半球光：用 `new THREE.PointLight(0xffee88, 1, 100, 2)` 创建点光，设置 `bulbLight.power = 1700`（流明，约 100W 灯泡），并 `bulbLight.castShadow = true`；用 `new THREE.HemisphereLight(0xddeeff, 0x0f0e0d, 0.02)` 创建半球光。
7. 用 InstancedMesh 渲染大量相似对象：用 `new THREE.SphereGeometry(0.1, 16, 16)` 和 `new THREE.MeshStandardMaterial({ color: 0xff0000 })`；创建 `new THREE.InstancedMesh(geometry, material, 1000)`；用 `new THREE.Matrix4()` 和 `new THREE.Color()`；循环中 `matrix.setPosition(Math.random() * 10 - 5, Math.random() * 10 - 5, Math.random() * 10 - 5)`、`instancedMesh.setMatrixAt(i, matrix)`、`instancedMesh.setColorAt(i, color.setHex(Math.random() * 0xffffff))`；设置 `instancedMesh.instanceMatrix.needsUpdate = true`；`scene.add(instancedMesh)`。
8. 加载 glTF 模型：用 `GLTFLoader` 和 `DRACOLoader`；调用 `dracoLoader.setDecoderPath('/draco/')`；调用 `gltfLoader.setDRACOLoader(dracoLoader)`；调用 `gltfLoader.load('model.glb', (gltf) => { ... })`；取 `const model = gltf.scene`；用 `model.traverse((child) => { if (child.isMesh) { child.castShadow = true; child.receiveShadow = true; } })`；`scene.add(model)`；若 `gltf.animations.length > 0`，创建 `new THREE.AnimationMixer(model)`，用 `mixer.clipAction(gltf.animations[0])` 创建 action，调用 `action.play()`，并在动画循环中调用 `mixer.update(deltaTime)`。
9. 配置阴影：设置 `renderer.shadowMap.enabled = true`；设置 `renderer.shadowMap.type = THREE.PCFSoftShadowMap` 或 `VSMShadowMap`；对方向光设置 `directionalLight.castShadow = true`；设置 `directionalLight.shadow.mapSize.width = 2048`、`directionalLight.shadow.mapSize.height = 2048`；设置 `directionalLight.shadow.camera.near = 0.5`、`directionalLight.shadow.camera.far = 50`、`directionalLight.shadow.camera.left = -10`、`directionalLight.shadow.camera.right = 10`、`directionalLight.shadow.camera.top = 10`、`directionalLight.shadow.camera.bottom = -10`；设置 `directionalLight.shadow.radius = 4`、`directionalLight.shadow.blurSamples = 8`；对 mesh 设置 `mesh.castShadow = true`、`mesh.receiveShadow = true`。
10. 实现 Raycasting 交互：创建 `new THREE.Raycaster()` 和 `new THREE.Vector2()`；在 click 事件中设置 `mouse.x = (event.clientX / window.innerWidth) * 2 - 1`、`mouse.y = -(event.clientY / window.innerHeight) * 2 + 1`；调用 `raycaster.setFromCamera(mouse, camera)`；调用 `raycaster.intersectObjects(scene.children, true)`；若 `intersects.length > 0`，取 `const object = intersects[0].object`，调用 `object.material.color.set(0xff0000)`。
11. 用 GSAP 集成动画：用 `import gsap from 'gsap';`；调用 `gsap.to(camera.position, { x: 5, y: 3, z: 10, duration: 2, ease: 'power2.inOut', onUpdate: () => { camera.lookAt(scene.position); } })`；调用 `gsap.to(mesh.rotation, { y: Math.PI * 2, duration: 3, repeat: -1, ease: 'none' })`。
12. 添加后处理：用 `EffectComposer`、`RenderPass`、`UnrealBloomPass`；创建 `const composer = new EffectComposer(renderer)`；调用 `composer.addPass(new RenderPass(scene, camera))`；创建 `new UnrealBloomPass(new THREE.Vector2(window.innerWidth, window.innerHeight), 1.5, 0.4, 0.85)`；调用 `composer.addPass(bloomPass)`；在动画循环中调用 `composer.render()`。
13. 复用几何体：不要在循环中为每个 mesh 新建 `THREE.BoxGeometry(1, 1, 1)`；在循环外创建 `const sharedGeometry = new THREE.BoxGeometry(1, 1, 1)`；循环中 `new THREE.Mesh(sharedGeometry, material)` 并 `scene.add(mesh)`。
14. 对数百或数千个相同对象使用 InstancedMesh：按 InstancedMesh 模式创建并设置矩阵与颜色，以减少 draw call。
15. 优化纹理：设置 `texture.generateMipmaps = true`；设置 `texture.minFilter = THREE.LinearMipmapLinearFilter`、`texture.magFilter = THREE.LinearFilter`；使用 2 的幂尺寸（512、1024、2048）；考虑用纹理图集合并多个小纹理。
16. 使用 LOD：创建 `const lod = new THREE.LOD()`；调用 `lod.addLevel(highDetailMesh, 0)`、`lod.addLevel(mediumDetailMesh, 50)`、`lod.addLevel(lowDetailMesh, 100)`；调用 `scene.add(lod)`。
17. 利用视锥剔除：Three.js 自动剔除相机视野外的对象；确保对象有正确包围球，调用 `mesh.geometry.computeBoundingSphere()`。
18. 释放场景资源：定义 `disposeScene`，用 `scene.traverse((object) => { ... })`；若 `object.geometry` 存在则 `object.geometry.dispose()`；若 `object.material` 存在，数组则 `object.material.forEach(material => material.dispose())`，否则 `object.material.dispose()`；最后 `renderer.dispose()`。
19. 使用 Animation Clocks 统一计时：创建 `const clock = new THREE.Clock()`；在 `animate` 中调用 `const deltaTime = clock.getDelta()`、`const elapsedTime = clock.getElapsedTime()`；用 deltaTime 做帧无关动画，例如 `mesh.rotation.y += deltaTime * Math.PI * 0.5`；然后 `renderer.render(scene, camera)`。
20. 设置相机参数：FOV 用 45-75°；near plane 尽可能远；far plane 尽可能近；aspect ratio 始终匹配 canvas 尺寸。
21. 按场景选择材质：`MeshBasicMaterial` 用于无光照平色（调试、UI）；`MeshLambertMaterial` 用于廉价漫反射（移动端）；`MeshPhongMaterial` 用于镜面高光（旧标准）；`MeshStandardMaterial` 用于 PBR、真实（推荐）；`MeshPhysicalMaterial` 用于高级 PBR（clearcoat、transmission）。
22. 遵循 Three.js 坐标系：右手坐标系；+Y 向上，+Z 朝向相机，+X 向右；旋转使用弧度（Math.PI 等于 180°）。
23. 组织场景：用 `THREE.Group()` 分组相关对象，例如 `building.add(walls, roof, windows)` 后 `scene.add(building)`；设置有意义名称，例如 `mesh.name = 'player-character'`，用 `scene.getObjectByName('player-character')` 查找。
24. 避免 resize 陷阱：窗口尺寸变化时始终更新 `camera.aspect` 和 `camera.updateProjectionMatrix()`。
25. 避免动画循环内存泄漏：不要在 `animate` 中创建 `new THREE.BoxGeometry()` 等新对象；在循环外创建并复用 geometry 等资源。
26. 确保阴影工作：在 renderer、lights、objects 上分别启用阴影，不要只设置其中一个。
27. 处理 Z-Fighting：增加 near plane 距离；减小 far plane 距离；避免重叠共面表面；设置 `material.polygonOffset = true` 和 `material.polygonOffsetFactor`。
28. 正确处理颜色空间：为纹理设置 `texture.colorSpace = THREE.SRGBColorSpace`；为渲染器设置 `renderer.outputColorSpace = THREE.SRGBColorSpace`。
29. 及时释放资源：不再需要时对 geometries、materials、textures、renderers 调用 `.dispose()`。
30. 编写自定义 Shader：用 `new THREE.ShaderMaterial({ uniforms: { uTime: { value: 0.0 }, uColor: { value: new THREE.Color(0x00ff00) } }, vertexShader: ..., fragmentShader: ... })`；vertexShader 中传递 `varying vec2 vUv`、设置 `gl_Position`；fragmentShader 中使用 `uniform float uTime`、`uniform vec3 uColor`、`varying vec2 vUv` 并设置 `gl_FragColor`。
31. 使用 Render Targets 渲染到纹理：创建 `new THREE.WebGLRenderTarget(512, 512)`；调用 `renderer.setRenderTarget(renderTarget)`；调用 `renderer.render(scene, camera)`；调用 `renderer.setRenderTarget(null)`；用 `renderTarget.texture` 作为 `map` 创建 `THREE.MeshBasicMaterial`。
32. 做 GPU 计算：使用 `GPUComputationRenderer` 实现粒子模拟、布料物理等。
33. 查阅 references 资源：使用 `references/api_reference.md` 快速查核心类（Scene、Camera、Renderer 等）API；使用 `references/materials_guide.md` 查材质类型与属性；使用 `references/optimization_checklist.md` 做性能优化策略。
34. 使用 scripts 资源：运行 `scripts/setup_scene.py` 生成 Three.js 场景样板代码；运行 `scripts/texture_optimizer.py` 批量优化纹理（resize、compress）；运行 `scripts/gltf_validator.py` 在使用前验证 glTF 模型。
35. 使用 assets 资源：从 `assets/starter_scene/` 取完整 HTML/JS 样板项目；从 `assets/shaders/` 取自定义 GLSL shader 示例（vertex、fragment）；从 `assets/hdri/` 取 PBR 环境贴图；从 `assets/draco/` 取 DRACO 解码器。
36. React 集成：Three.js 与 React Three Fiber 自然集成；React 项目中使用 react-three-fiber 技能中的 React 集成模式。

适用边界 · 注意事项

• 需要 React 声明式集成时，优先使用 react-three-fiber 技能，而不是直接手写 Three.js。
• 需要滚动驱动动画时，配合 gsap-scrolltrigger 技能；需要 UI 动画时使用 motion-framer 技能。
• 仅需简单 2D 或 DOM/CSS 动画、无需 3D/WebGL 时，不必引入 Three.js。