three-best-practices

Three.js 最佳实践

Three.js 应用的综合性能优化指南。包含 18 个类别、120 多条规则，并按影响程度排序。

来源与致谢

本技能汇集了多个权威来源的最佳实践：

• 由 mrdoob 维护的 Three.js llms 分支中的官方指南
• Utsubo 编写的 100 Three.js Tips——一份优秀的综合指南，涵盖 WebGPU、资源优化和性能技巧

适用场景

在以下情况下，请参考这些指南：

• 搭建新的 Three.js 项目
• 编写或审查 Three.js 代码
• 优化性能或修复内存泄漏
• 使用自定义着色器（GLSL 或 TSL）
• 实现 WebGPU 功能
• 使用 WebXR 构建 VR/AR 体验
• 集成物理引擎
• 针对移动设备进行优化

按优先级划分的规则类别

优先级	类别	影响	前缀
0	现代设置与导入	基础	setup-
1	内存管理与释放	严重	memory-
2	渲染循环优化	严重	render-
3	绘制调用优化	严重	drawcall-
4	几何体与缓冲区管理	高	geometry-
5	材质与纹理优化	高	material-
6	资源压缩	高	asset-
7	光照与阴影	中高	lighting-
8	场景图组织	中	scene-
9	着色器最佳实践（GLSL）	中	shader-
10	TSL（Three.js 着色语言）	中	tsl-
11	WebGPU 渲染器	中	webgpu-
12	加载与资源	中	loading-
13	Core Web Vitals	中高	vitals-
14	摄像机与控制	中低	camera-
15	动画系统	中	animation-
16	物理集成	中	physics-
17	WebXR / VR / AR	中	webxr-
18	音频	中低	audio-
19	后期处理	中	postpro-
20	移动端优化	高	mobile-
21	生产环境	高	error-、migration-
22	调试与开发者工具	低	debug-

快速参考

0. 现代设置（基础）

• setup-use-import-maps - 使用 Import Maps，而非旧式 CDN 脚本
• setup-choose-renderer - WebGLRenderer（默认）与 WebGPURenderer（TSL/计算）
• setup-animation-loop - 使用 renderer.setAnimationLoop()，而非手动 RAF
• setup-basic-scene-template - 完整的现代场景模板

1. 内存管理（严重）

• memory-dispose-geometry - 始终释放几何体
• memory-dispose-material - 始终释放材质和纹理
• memory-dispose-textures - 释放动态创建的纹理
• memory-dispose-render-targets - 始终释放 WebGLRenderTarget
• memory-dispose-recursive - 对层级结构使用递归释放
• memory-dispose-on-unmount - 在 React 清理/卸载时释放资源
• memory-renderer-dispose - 销毁视图时释放渲染器
• memory-reuse-objects - 重用几何体和材质

2. 渲染循环（严重）

• render-single-raf - 使用单个 requestAnimationFrame 循环
• render-conditional - 对静态场景按需渲染
• render-delta-time - 动画使用增量时间
• render-avoid-allocations - 绝不在渲染循环中分配内存
• render-cache-computations - 缓存开销较大的计算结果
• render-frustum-culling - 启用视锥体剔除
• render-update-matrix-manual - 对静态对象禁用自动矩阵更新
• render-pixel-ratio - 将像素比限制为 2
• render-antialias-wisely - 谨慎使用抗锯齿

3. 绘制调用优化（关键）

• draw-call-optimization - 将每帧绘制调用数控制在 100 次以下
• geometry-instanced-mesh - 对相同物体使用 InstancedMesh
• geometry-batched-mesh - 对不同几何体（使用相同材质）使用 BatchedMesh
• geometry-merge-static - 使用 BufferGeometryUtils 合并静态几何体

4. 几何体（高）

• geometry-buffer-geometry - 始终使用 BufferGeometry
• geometry-merge-static - 合并静态几何体
• geometry-instanced-mesh - 对相同物体使用 InstancedMesh
• geometry-lod - 对复杂模型使用细节层次（Level of Detail）
• geometry-index-buffer - 使用索引几何体
• geometry-vertex-count - 尽量减少顶点数
• geometry-attributes-typed - 使用合适的类型化数组
• geometry-interleaved - 考虑使用交错缓冲区

5. 材质与纹理（高）

• material-reuse - 在多个网格之间复用材质
• material-simplest-sufficient - 使用满足需求的最简单材质
• material-texture-size-power-of-two - 使用二次幂纹理尺寸
• material-texture-compression - 使用压缩纹理（KTX2/Basis）
• material-texture-mipmaps - 根据需要启用 Mipmap
• material-texture-anisotropy - 为地面使用各向异性过滤
• material-texture-atlas - 使用纹理图集
• material-avoid-transparency - 尽量减少透明材质
• material-onbeforecompile - 使用 onBeforeCompile 修改着色器（或使用 TSL）

6. 资源压缩（高）

• asset-compression - Draco、Meshopt、KTX2 压缩指南
• asset-draco - 几何体尺寸减少 90-95%
• asset-ktx2 - GPU 压缩纹理（UASTC 与 ETC1S）
• asset-meshopt - Draco 的替代方案，解压速度更快
• asset-lod - 使用细节层次，帧率可提升 30-40%

7. 光照与阴影（中高）

• lighting-limit-lights - 将活动光源限制在 3 个或更少
• lighting-shadows-advanced - PointLight 的开销、CSM、假阴影
• lighting-bake-static - 为静态场景烘焙光照
• lighting-shadow-camera-tight - 使阴影相机的范围尽可能贴合
• lighting-shadow-map-size - 选择合适的阴影分辨率（512-4096）
• lighting-shadow-selective - 有选择地启用阴影
• lighting-shadow-cascade - 在大型场景中使用 CSM
• lighting-shadow-auto-update - 在静态场景中禁用 autoUpdate
• lighting-probe - 使用光照探针
• lighting-environment - 使用环境贴图提供环境光
• lighting-fake-shadows - 使用渐变平面实现低开销接触阴影

8. 场景图（中）

• scene-group-objects - 使用 Group 组织对象
• scene-layers - 使用 Layer 进行选择性渲染
• scene-visible-toggle - 使用 visible 标志，而非添加或移除对象
• scene-flatten-static - 展平静态层级结构
• scene-name-objects - 为对象命名以便调试
• object-pooling - 复用对象，而非反复创建和销毁

9. 着色器 GLSL（中）

• shader-precision - 在移动设备上使用 mediump（速度约快 2 倍）
• shader-mobile - 针对移动设备进行优化（varyings、分支）
• shader-avoid-branching - 使用 mix/step 替代条件语句
• shader-precompute-cpu - 在 CPU 上预计算
• shader-avoid-discard - 避免使用 discard，改用 alphaTest
• shader-texture-lod - 对已知的 Mipmap 层级使用 textureLod
• shader-uniform-arrays - 优先使用 uniform 数组
• shader-varying-interpolation - 在移动设备上将 varying 数量限制为 3 个
• shader-pack-data - 将数据打包到 RGBA 通道中
• shader-chunk-injection - 使用 Three.js 着色器代码块

10. TSL - Three.js Shading Language（中等）

• tsl-why-use - 使用 TSL，而不是 onBeforeCompile
• tsl-setup-webgpu - TSL 的 WebGPU 设置
• tsl-complete-reference - 完整的 TSL 类型系统和函数
• tsl-material-slots - 材质节点属性参考
• tsl-node-materials - 使用 NodeMaterial 类
• tsl-basic-operations - 类型、运算和 swizzling
• tsl-functions - 使用 Fn() 创建 TSL 函数
• tsl-conditionals - TSL 中的 if、select 和循环
• tsl-textures - 纹理和三平面映射
• tsl-noise - 内置噪声函数（mx_noise_float、mx_fractal_noise）
• tsl-post-processing - 泛光、模糊、景深、环境光遮蔽
• tsl-compute-shaders - GPGPU 和计算操作
• tsl-glsl-to-tsl - GLSL 到 TSL 的转换

11. WebGPU Renderer（中等）

• webgpu-renderer - 设置、浏览器支持和迁移指南
• webgpu-render-async - 在计算密集型场景中使用 renderAsync
• webgpu-feature-detection - 检查适配器功能
• webgpu-instanced-array - GPU 持久化缓冲区
• webgpu-storage-textures - 可读写的计算纹理
• webgpu-workgroup-memory - 共享内存（快 10–100 倍）
• webgpu-indirect-draws - GPU 驱动的渲染

12. 加载与资源（中等）

• loading-draco-compression - 对大型网格使用 Draco
• loading-gltf-preferred - 使用 glTF 格式
• gltf-loading-optimization - 完整的加载器设置，包含 DRACO/Meshopt/KTX2
• loading-progress-feedback - 显示加载进度
• loading-async-await - 使用 async/await 加载
• loading-lazy - 延迟加载非关键资源
• loading-cache-assets - 启用缓存
• loading-dispose-unused - 卸载未使用的资源

13. Core Web Vitals（中等偏高）

• core-web-vitals - 面向 3D 的 LCP、FID、CLS 优化
• vitals-lazy-load - 使用 IntersectionObserver 延迟加载首屏以下的 3D 内容
• vitals-code-split - 动态导入 Three.js 模块
• vitals-preload - 使用 link 标签预加载关键资源
• vitals-progressive-loading - 从低分辨率到高分辨率渐进式加载
• vitals-placeholders - 加载期间显示占位几何体
• vitals-web-workers - 将繁重工作交给 workers 处理
• vitals-streaming - 按区块流式加载大型场景

14. 摄像机与控制（低至中等）

• camera-near-far - 设置紧凑的近裁剪面和远裁剪面
• camera-fov - 选择合适的 FOV
• camera-controls-damping - 使用阻尼实现平滑控制
• camera-resize-handler - 正确处理尺寸调整
• camera-orbit-limits - 设置环绕控制限制

15. 动画（中等）

• animation-system - AnimationMixer、混合、变形目标、骨骼动画

16. 物理（中等）

• physics-integration - Rapier、Cannon-es 集成模式
• physics-compute-shaders - 使用计算着色器实现 GPU 物理

17. WebXR（中等）

• webxr-setup - VR/AR 按钮、控制器、命中测试

18. 音频（低至中等）

• audio-spatial - PositionalAudio、HRTF、空间音效

19. 后期处理（中等）

• postprocessing-optimization - pmndrs/postprocessing 指南
• postpro-renderer-config - 为后期处理禁用 AA、stencil 和 depth
• postpro-merge-effects - 在单次渲染过程中合并效果
• postpro-selective-bloom - 使用选择性泛光提升性能
• postpro-resolution-scaling - 使用半分辨率，将 FPS 提升至 2 倍
• postpro-webgpu-native - 基于 TSL 的 WebGPU 后期处理

20. 优化（高）

• mobile-optimization - 移动设备专属优化和检查清单
• raycasting-optimization - BVH、图层、GPU 拾取

21. 生产环境（高）

• error-handling-recovery - WebGL 上下文丢失与恢复
• migration-checklist - 按版本列出的破坏性变更

22. 调试与开发工具（低优先级）

• debug-devtools - 完整的调试工具包
• debug-stats-gl - 使用 stats-gl 监控 WebGL/WebGPU
• debug-lil-gui - 使用 lil-gui 实时调整参数
• debug-spector - 使用 Spector.js 捕获 WebGL 帧
• debug-renderer-info - 监控绘制调用和内存
• debug-three-mesh-bvh - 使用 BVH 实现快速射线投射
• debug-context-lost - 处理 WebGL 上下文丢失
• debug-animation-loop-profiling - 分析渲染循环各部分的性能
• debug-conditional - 在生产环境中移除调试代码

如何使用

阅读各规则文件，了解详细说明和代码示例：

rules/setup-use-import-maps.md
rules/memory-dispose-geometry.md
rules/tsl-complete-reference.md
rules/mobile-optimization.md

每个规则文件都包含：

• 简要说明其重要性
• 附带说明的错误代码示例
• 附带说明的正确代码示例
• 补充背景信息和参考资料

关键模式

现代导入映射

<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/[email protected]/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/[email protected]/examples/jsm/",
    "three/tsl": "https://cdn.jsdelivr.net/npm/[email protected]/build/three.tsl.js"
  }
}
</script>

正确释放资源

function disposeObject(obj) {
  if (obj.geometry) obj.geometry.dispose();
  if (obj.material) {
    if (Array.isArray(obj.material)) {
      obj.material.forEach(m => m.dispose());
    } else {
      obj.material.dispose();
    }
  }
}

TSL 基本用法

import { texture, uv, color, time, sin } from 'three/tsl';

const material = new THREE.MeshStandardNodeMaterial();
material.colorNode = texture(map).mul(color(0xff0000));
material.colorNode = color(0x00ff00).mul(sin(time).mul(0.5).add(0.5));

移动设备检测

const isMobile = /Android|iPhone|iPad|iPod/i.test(navigator.userAgent);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, isMobile ? 1.5 : 2));