threejs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Three.js

Overview

概述

Guides building high-performance 3D web experiences with Three.js, WebGPU-first rendering, TSL (Three Shader Language), and React Three Fiber. Covers scene architecture, asset compression, draw call budgets, and React 19 / Next.js integration patterns.

When to use: Creating 3D scenes, WebGPU rendering setup, TSL shader authoring, asset optimization (Draco/KTX2), React Three Fiber composition, Next.js streaming for 3D content, loading GLTF models, setting up lighting and shadows, animation playback and blending.

When NOT to use: 2D canvas animations (use Canvas API), simple SVG graphics, server-side rendering without client hydration, projects targeting pre-2022 hardware exclusively.

指导你使用Three.js、WebGPU优先的渲染模式、TSL（Three着色器语言）和React Three Fiber构建高性能3D网页体验，涵盖场景架构、资源压缩、绘制调用预算，以及React 19 / Next.js集成模式。

适用场景： 创建3D场景、WebGPU渲染配置、TSL着色器开发、资源优化（Draco/KTX2）、React Three Fiber组合开发、为3D内容配置Next.js流式传输、加载GLTF模型、设置光照与阴影、动画播放与融合。

不适用场景： 2D画布动画（请使用Canvas API）、简单SVG图形、无客户端水合的服务端渲染、仅面向2022年之前硬件的项目。

Quick Reference

快速参考

Pattern	API / Approach	Key Points
WebGPU renderer	`import * as THREE from 'three/webgpu'`	Must `await renderer.init()` before first render
R3F canvas	`<Canvas gl={...}>` with Suspense	Wrap in `<Suspense>` for streaming support
Frame updates	`useFrame((state, delta) => ...)`	Mutate refs directly; never use `setState`
TSL shaders	`import { ... } from 'three/tsl'`	Node-based; compiles to WGSL or GLSL
Instancing	`<instancedMesh>` with matrix updates	Single draw call for repeated geometry
Batched mesh	`BatchedMesh` (r156+)	Different geometries sharing one material
Draco compression	`gltf-pipeline -i in.gltf -o out.glb -d`	Up to 90% geometry size reduction
KTX2 textures	Basis Universal via `toktx`	Stays compressed in VRAM
LOD	`THREE.LOD` with distance thresholds	Swap detail levels by camera distance
On-demand render	`<Canvas frameloop="demand">`	Only render when scene state changes
Cleanup	`.dispose()` on unmount	Geometries, materials, and textures
Compute shaders	`Fn(() => {...})().compute(count)`	GPU-side physics, particles, flocking
Lighting	`DirectionalLight` , `SpotLight` , `HemisphereLight`	Enable `shadowMap` on renderer + `castShadow` on light
GLTF loading	`GLTFLoader` + `DRACOLoader`	Draco for geometry compression; traverse for shadows
Animation	`AnimationMixer` + `clipAction()`	Update with `clock.getDelta()` every frame
Crossfade	`action.fadeOut()` / `action.fadeIn()`	Weight-based blending between walk/run/idle
Environment maps	`RGBELoader` + `PMREMGenerator`	Set `scene.environment` for PBR reflections
Raycasting	`Raycaster.setFromCamera(pointer, cam)`	Mouse/touch picking; use `recursive: true` for GLTF
Morph targets	`mesh.morphTargetInfluences[index]`	Facial animation, blend shapes from GLTF

模式	API / 实现方式	核心要点
WebGPU渲染器	`import * as THREE from 'three/webgpu'`	首次渲染前必须执行 `await renderer.init()`
R3F画布	`<Canvas gl={...}>` 配合Suspense使用	外层包裹 `<Suspense>` 以支持流式传输
帧更新	`useFrame((state, delta) => ...)`	直接修改引用值，禁止使用 `setState`
TSL着色器	`import { ... } from 'three/tsl'`	基于节点开发，可编译为WGSL或GLSL
实例化	`<instancedMesh>` 配合矩阵更新	重复几何图形仅需单次绘制调用
批量网格	`BatchedMesh` (r156+)	不同几何图形可共用同一份材质
Draco压缩	`gltf-pipeline -i in.gltf -o out.glb -d`	最高可减少90%几何体积
KTX2纹理	基于 `toktx` 实现Basis Universal压缩	可在显存中保持压缩状态
层级细节	`THREE.LOD` 配合距离阈值使用	根据相机距离切换细节等级
按需渲染	`<Canvas frameloop="demand">`	仅当场景状态变更时渲染
资源清理	组件卸载时调用 `.dispose()`	需清理几何、材质和纹理
计算着色器	`Fn(() => {...})().compute(count)`	可实现GPU端物理模拟、粒子系统、群体运动
光照	`DirectionalLight` , `SpotLight` , `HemisphereLight`	需同时开启渲染器的 `shadowMap` 和光源的 `castShadow`
GLTF加载	`GLTFLoader` + `DRACOLoader`	用Draco做几何压缩，遍历节点开启阴影
动画	`AnimationMixer` + `clipAction()`	每帧使用 `clock.getDelta()` 更新动画
交叉淡入淡出	`action.fadeOut()` / `action.fadeIn()`	基于权重实现行走/奔跑/待机状态的融合
环境贴图	`RGBELoader` + `PMREMGenerator`	设置 `scene.environment` 实现PBR反射
射线检测	`Raycaster.setFromCamera(pointer, cam)`	实现鼠标/触摸点选，GLTF模型需设置 `recursive: true`
形变目标	`mesh.morphTargetInfluences[index]`	实现面部动画、GLTF导出的混合形状

Common Mistakes

常见错误

Mistake	Correct Pattern
Allocating `new THREE.Vector3()` or `new THREE.Color()` inside `useFrame`	Pre-allocate outside the loop to avoid GC pressure every frame
Using `requestAnimationFrame` manually in React projects	Use R3F's `useFrame` hook for frame-by-frame updates
Not awaiting `renderer.init()` for WebGPU	Always `await renderer.init()` before the first render to avoid race conditions
Loading assets without `<Suspense>` boundaries	Wrap `<Canvas>` in `<Suspense>` to prevent main thread blocking
Using high-poly models for background or distant elements	Use LOD (Level of Detail) or Impostors to reduce draw calls
Using `setState` inside render loop for animations	Mutate refs directly via `useFrame` for frame-by-frame updates
Speed tied to frame rate ( `rotation += 0.01` )	Multiply by `delta` for frame-rate-independent motion
Not using `clock.getDelta()` for `mixer.update()`	Always pass delta time to `mixer.update(delta)` for correct animation speed
Forgetting to dispose loaded GLTF models	Traverse and dispose geometries, materials, and textures on removal
Shadow map enabled on renderer but not on the light	Set both `renderer.shadowMap.enabled` and `light.castShadow = true`
Large `far/near` ratio on camera	Keep ratio small to avoid z-fighting; set `near` as large as possible

错误做法	正确方案
在 `useFrame` 中创建 `new THREE.Vector3()` 或 `new THREE.Color()` 实例	在循环外提前预分配实例，避免每帧产生GC压力
在React项目中手动使用 `requestAnimationFrame`	使用R3F的 `useFrame` 钩子实现逐帧更新
WebGPU渲染时未等待 `renderer.init()` 执行完成	首次渲染前必须 `await renderer.init()` ，避免出现竞态条件
加载资源时没有 `<Suspense>` 边界	外层包裹 `<Suspense>` 避免阻塞主线程
背景或远处元素使用高多边形模型	使用LOD（层级细节）或 impostor 减少绘制调用
在渲染循环中使用 `setState` 实现动画	通过 `useFrame` 直接修改引用值实现逐帧更新
动画速度与帧率绑定（如 `rotation += 0.01` ）	乘以 `delta` 实现帧率无关的运动
`mixer.update()` 未传入 `clock.getDelta()`	始终向 `mixer.update(delta)` 传入时间增量，保证动画速度正确
忘记销毁加载的GLTF模型	移除时遍历并销毁几何、材质和纹理
仅开启渲染器的阴影映射，未开启光源的阴影投射	同时设置 `renderer.shadowMap.enabled` 和 `light.castShadow = true`
相机的 `far/near` 比值过大	保持较小比值避免z-fighting，尽量将 `near` 设置得大一些

Delegation

任务委派

Asset and scene graph exploration: Use
```
Explore
```
agent
Multi-file scene refactoring and optimization passes: Use
```
Task
```
agent
3D architecture and rendering pipeline planning: Use
```
Plan
```
agent

资源与场景图探索：使用
```
Explore
```
Agent
多文件场景重构与优化流程：使用
```
Task
```
Agent
3D架构与渲染管线规划：使用
```
Plan
```
Agent

References

参考资料

Scene, lighting, and model loading
Animation system and blending
Performance and asset optimization
WebGPU and TSL shader patterns
React Three Fiber patterns and Next.js integration

场景、光照与模型加载
动画系统与融合
性能与资源优化
WebGPU和TSL着色器模式
React Three Fiber模式与Next.js集成