threejs

name	threejs
description	当用 Three.js 在 web 上构建或调试交互式 3D 场景（scene/camera/renderer、光照/材质、GLTF 加载、控制器、性能）时使用。对交付 3D UI 时刻的设计师很有帮助。

Three.js —— WebGL 3D 场景技能

何时使用

• 真 3D：产品旋转、交互式主视觉场景、着色器/材质特效、3D 数据可视化
• 你需要超越“背景特效”的完整控制
• 你能为资产流水线 + 性能调优安排时间

核心思维模型

• 创建：
  • Scene（根场景图）
  • Camera（Perspective/Orthographic）
  • Renderer（WebGLRenderer）
  • Mesh = Geometry + Material
  • 光照（若使用非 unlit 材质）
• 渲染循环：
  • requestAnimationFrame(animate)
  • 更新基于时间的动画、控制器、mixer，然后 renderer.render(scene, camera)

关键 API/模式

• 初始化：
  • const renderer = new THREE.WebGLRenderer({ canvas, antialias, alpha })
  • renderer.setSize(width, height, false)
  • renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))
• 相机：
  • camera.aspect = width / height; camera.updateProjectionMatrix()
• 场景图：
  • scene.add(object) / object.position/rotation/scale
• 加载资产：
  • GLTFLoader（模型）、TextureLoader（图片）、DRACOLoader（压缩 glTF）
• 控制器（常用）：
  • OrbitControls（调试/产品）、PointerLockControls（FPS）、自定义指针处理
• 清理（在 SPA 中很重要）：
  • geometry.dispose()、material.dispose()、texture.dispose()、renderer.dispose()
  • 移除事件监听器；取消 RAF。

常见坑

• 不处理 resize → 渲染被拉伸/裁切
• devicePixelRatio 过高 → 移动 GPU 崩溃
• 泄漏 WebGL 资源（未 dispose）→ 路由切换后崩溃
• 加载巨型纹理/模型 → 启动慢；使用压缩纹理、Draco/KTX2、更小的贴图
• 使用过多光照/阴影 → 开销大；尽量用烘焙纹理伪造光照

快速食谱

1）最小旋转立方体

import * as THREE from "three";

const canvas = document.querySelector("#c");
const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });

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

const geom = new THREE.BoxGeometry(1, 1, 1);
const mat = new THREE.MeshStandardMaterial({ color: 0x7c3aed });
const mesh = new THREE.Mesh(geom, mat);
scene.add(mesh);

scene.add(new .(, ));
 dir =  .(, );
dir..(, , );
scene.(dir);

 () {
   w = canvas.;
   h = canvas.;
  renderer.(w, h, );
  renderer.(.(., ));
  camera. = w / h;
  camera.();
}
.(, resize);
();

 () {
  mesh.. = t * ;
  renderer.(scene, camera);
  (animate);
}
(animate);

2）尊重减弱动效

• 若 prefers-reduced-motion: reduce，渲染一个静止帧（不用 RAF）或放慢更新。

需要向用户询问的

• 这是装饰性（主视觉）还是功能性 3D（产品查看器）？
• 目标设备：移动端？较旧的 iPhone？
• 资产格式可用性（glTF、HDRI、纹理）与文件大小约束
• 无障碍/减弱动效要求