threejs-fundamentals

Three.js 基础

此技能用于搭建通用 Three.js Web 体验的渲染基础。 对于可玩游戏的系统、生命周期或发布工作，请使用 web-game-development； 对于范围较窄的渲染问题，请转至对应的 threejs-* 技能。

何时使用此技能

• 搭建或修复场景、相机、渲染器、画布所有权或动画循环
• 选择透视投影或正交投影，或修正世界坐标与局部坐标变换
• 让渲染具备响应式、颜色管理能力，并适配高 DPI 显示屏
• 排查空白场景、内容被裁切、相机取景错误或 GPU 资源泄漏

说明

步骤 1：明确项目约定

1. 更改导入方式或初始化代码前，先查看已安装的 three 版本，以及现有渲染器和画布的所有权。
2. 渲染循环和尺寸调整监听器都应只有一个所有者。React Three Fiber 等框架包装器负责管理这些生命周期事项；不要再添加互相竞争的原始循环。
3. 使用特定后端的 API 前，先确认渲染后端。此技能默认使用 WebGLRenderer；使用 WebGPU 模式时，请根据已安装的 Three.js 版本核实相关用法。

步骤 2：构建最小可见场景

在加入加载器、着色器或后期处理之前，先使用明确的场景、相机、渲染器、一个受光网格和渲染循环。

import * as THREE from "three";

const width = window.innerWidth;
const height = window.innerHeight;

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(50, width / height, 0.1, 100);
camera.position.set(0, 1, 4);

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(width, height);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
renderer.outputColorSpace = THREE.SRGBColorSpace;

const mesh = new THREE.Mesh(
  new THREE.BoxGeometry(),
  new THREE.MeshStandardMaterial({ color: 0x4f8cff }),
);
scene.add(new THREE.HemisphereLight(0xffffff, 0x334455, 2));
scene.add(mesh);

function render() {
  renderer.render(scene, camera);
  requestAnimationFrame(render);
}
render();

使用 Group 为一个功能创建单一变换根节点。有意识地修改 position、quaternion 或 scale；局部坐标会通过父级逐层组合，而场景尚未渲染时，世界空间查询需要调用 updateWorldMatrix。

步骤 3：明确处理尺寸调整和资源释放

function resize(width, height) {
  camera.aspect = width / height;
  camera.updateProjectionMatrix();
  renderer.setSize(width, height, false);
}

function disposeObject(root) {
  root.traverse((object) => {
    object.geometry?.dispose();
    const materials = Array.isArray(object.material)
      ? object.material
      : [object.material];
    for (const material of materials) material?.dispose();
  });
}

也要释放该功能拥有的纹理和渲染目标。所有使用者都不再需要共享资源后，才能将其释放。

步骤 4：验证可观察到的渲染行为

• 确认在目标画布尺寸下，网格可见且相机取景稳定。
• 在狭窄、宽屏和高 DPI 场景下调整尺寸；绘图缓冲区不得发生拉伸。
• 检查浏览器控制台中的 WebGL 警告；仅将 renderer.info 用作诊断工具，不要将其视为测试判定标准。
• 如有相关配置，运行代码库的构建、类型检查以及相关视觉或浏览器测试。

选择指南

需求	使用
场景图、相机、渲染器、变换、生命周期	此技能
自定义顶点、实例化或 BufferGeometry	threejs-geometry
PBR 属性或网格表面外观	threejs-materials
灯光、阴影或基于图像的光照	threejs-lighting
贴图、UV、HDR 背景或渲染目标	threejs-textures
模型/资源加载和进度	threejs-loaders
AnimationMixer、动画片段、骨骼或变形	threejs-animation
光线投射、控件、拾取或输入	threejs-interaction
GLSL 或材质着色器扩展	threejs-shaders
EffectComposer 屏幕空间处理通道	threejs-postprocessing

示例

透视产品视图

使用 PerspectiveCamera 呈现符合直觉的物体视图。只有在确有需要时才设置刻意偏小的近裁剪面；不必要地将 near 值设得过小会浪费深度精度，并导致 Z-fighting。

类等距棋盘视图

当比例必须随深度保持不变时，使用 OrthographicCamera。调整尺寸时，根据纵横比重新计算 left/right/top/bottom，然后调用 updateProjectionMatrix()。

最佳实践

1. 每个画布只设置一个 requestAnimationFrame 所有者。
2. 限制像素比；不受限制的设备像素比会悄然增加 GPU 开销。
3. 进行常规 PBR 渲染时，使用 MeshStandardMaterial 并设置合理的灯光；不要用任意颜色值来弥补场景缺少光照的问题。
4. 相机裁剪面应尽可能贴近场景范围。
5. 为每项由功能分配的 GPU 资源配套提供释放流程。

参考资料

• Three.js 基础知识源代码覆盖范围
• Three.js 文档
• Three.js 手册：创建场景