Three.js 场景搭建

要解决的问题

three.js 虽然功能强大，但入门门槛并不低。很多开发者第一次接触时，会遇到各种"卡壳"的情况：浏览器控制台报错 Failed to resolve module specifier "three"，画布一片漆黑却找不到原因，或者画面在窗口缩放时被拉伸变形。这些问题的根源在于 three.js 的初始化流程涉及多个相互关联的步骤——模块加载、场景图构建、渲染循环、事件处理——任何一个环节出错都会让整个应用"静默失败"。

这个技能解决的就是从零搭建 three.js 应用时的"脚手架"问题。

核心能力与关键步骤

ES 模块加载是 r147 之后的强制要求。技能使用 HTML import map 将 three 和 three/addons/ 映射到正确的路径，确保浏览器能正确解析裸模块说明符。如果项目使用 Vite 或 webpack 等打包工具，则直接 npm i three 即可，导入语句保持不变。

场景三件套是 three.js 的基础架构：

• Scene 作为场景图的根节点，管理所有 3D 对象的父子关系
• PerspectiveCamera 定义视锥体参数（fov、aspect、near、far），通常需要从原点向后移动才能看到物体
• WebGLRenderer 负责将场景渲染到 DOM 中的 <canvas> 元素

渲染循环使用 renderer.setAnimationLoop(fn) 替代传统的 requestAnimationFrame。这是现代且兼容 WebXR 和 WebGPU 的方式。配合 Clock 对象可以获取帧间隔时间，实现平滑的动画更新。

响应式缩放需要同步更新渲染器尺寸和相机的宽高比：

• 调用 renderer.setSize(width, height)
• 更新 camera.aspect = width / height
• 调用 camera.updateProjectionMatrix()

OrbitControls 提供轨道旋转、平移和缩放功能，是开发阶段验证场景是否正确的关键工具。

适用边界与注意点

这个技能专注于 three.js 的基础场景搭建，不涉及以下内容：

• 模型加载：.gltf/.glb 格式的模型加载和骨骼动画请使用 threejs-gltf-loading
• 材质与光照：PBR 材质、灯光、阴影和环境贴图请使用 threejs-materials-lighting
• 2D 渲染：如果需要 2D 图形请选择 PixiJS

常见陷阱包括：相机放在原点导致看到物体内部（画面全黑）、使用了需要光照的 MeshStandardMaterial 但没有添加光源、忘记在渲染循环中调用 renderer.render()、启用了 enableDamping 但忘记每帧调用 controls.update() 等。