1. 先把 Three.js 的定位说清楚
Three.js 是浏览器里做 3D 场景的开源库，用 JavaScript 直接调用，专门解决“我想在网页上加一块能转、能缩放、能跑动画的三维画面，但又不想碰底层图形接口那一堆矩阵和着色器”这个具体问题。它把 WebGL 那一层繁琐的初始化、状态切换、坐标变换、材质编译全部封装成一个个看得懂的对象，比如场景、相机、网格、材质、灯光。你只要描述“这里放一个立方体，那里点一盏灯”，剩下的交给它。这篇内容适合三类人看：做前端想往可视化方向走的、做产品原型需要快速出 3D 效果的、以及自学过几次 WebGL 但每次都在第一个三角形上卡住的人。
我得先泼一盆冷水，说清楚它的能力边界，不然预期一旦跑偏，后面全是内耗。Three.js 不是建模工具，它不负责“做出一个模型”，模型得靠外部软件产出，它只负责“把模型展示出来并让它动起来”；它也不是游戏引擎，没有自带物理系统、寻路、场景编辑器、序列化关卡那一整套东西，物理、碰撞、状态管理需要你另外接库或自己写。它最强的地方在于：中小型 3D 可视化、产品展示配置器、数据图表的三维化表达、展厅漫游、简单的交互动效页。这些场景里，它能在几百 KB 的体积内给你一个完整可用的渲染管线，性价比极高。
1.1 为什么很多人绕不开它
原生 WebGL 的学习曲线是个陡坡，我见过太多人倒在画第一个三角形的路上：先是创建上下文，然后写几百行着色器代码，再手动处理顶点缓冲、索引缓冲、矩阵乘法、透视投影变换。这中间任何一个环节写错一个字母，屏幕上就是一片纯黑，没有任何报错告诉你错在哪。Three.js 把这套流程拆成了几个有语义的类，报错信息也直接指向具体对象，调试体验完全是两个量级。
更实际的一点是生态。模型加载有一整套 Loader，控制器有现成的轨道控制、飞行控制，后期效果有 EffectComposer，辅助调试有坐标轴、网格、包围盒、性能监视器。你不需要从零组装每一个零件。很多人第一次用它搭出一个能旋转的模型，代码量不到三十行，这种即时反馈对于长期学习特别重要。
1.2 它和别的方案怎么选
选型这一步最好不要拍脑袋，我习惯先问三个问题：交付环境是什么、内容复杂度有多高、后续谁来维护。如果交付环境只有浏览器，内容以展示为主，那 Three.js 基本是默认答案。如果内容里有大量物理交互、角色动画树、粒子十万级，那我更倾向于考虑专门的引擎，因为它们在这些方向上已经做了深度优化。
| 方案 | 上手成本 | 包体 | 适合场景 | 明显短板 |
|---|---|---|---|---|
| Three.js | 中低 | 中 | 产品展示、三维图表、展厅漫游、动效页 | 无物理、无编辑器 |
| 原生 WebGL | 高 | 极低 | 极度定制化的着色器效果、极致性能 | 开发效率极低 |
| 游戏引擎的 Web 导出 | 中 | 高 | 完整小游戏、复杂交互场景 | 首屏加载重、包体大 |
| CSS 3D 变换 | 极低 | 极低 | 卡片翻转、简单图层透视 | 无法做真实光照与模型 |
提示：包体这一栏不要只看库本身，模型、贴图、解码器往往才是体积大头，一个带压缩贴图的 GLB 轻易就上到几 MB，比库本身大十倍很正常。
1.3 版本选择与工程约束
版本号这件事必须重视。库的迭代速度很快，近几年的版本在颜色空间、光照单位、渲染器默认行为上做过好几次不兼容变更，网上大量教程停留在一两个大版本之前，照抄很容易出现“颜色发灰”“光怎么调都不亮”“模型半透明出问题”这类莫名其妙的症状。我在新项目里的固定做法是：锁死小版本号，不要用范围符号，同时在文档里记下当前版本，后续升级时集中做一次回归验证。
另一个容易被忽略的约束是浏览器兼容。目前主流浏览器对 WebGL2 的支持已经比较完整，但仍有部分老旧设备或受限环境只支持 WebGL1。库在新版本里对 WebGL1 的支持是逐步收敛的，如果你的用户分布里有大量低端安卓机，建议在初始化时加一个能力检测，把 WebGL2 作为优先项，检测失败时降级到 WebGL1 渲染器并关闭一部分吃性能的特性，比如软阴影和高精度贴图，别等到白屏了再回头查。
2. 核心概念拆解：三件套加一棵树
Three.js 的心智模型可以压缩成一句话：一棵场景树，一台相机，一个渲染器。渲染器每帧做的事，就是拿相机去拍这棵树，把拍到的结果画到 canvas 上。所有其他的概念，几何体、材质、灯光、模型、控制器，全都是挂在这棵树上的节点或者服务于这次拍摄的辅助对象。这个模型建立起来之后，你读任何示例代码都会顺畅很多。
2.1 场景图与坐标系
场景（Scene）本质上是一个容器节点，它继承自 Object3D，而 Object3D 就是这棵树的基节点，每个节点都有位置、旋转、缩放三个变换属性，还带一个 children 数组。父节点移动，所有子节点跟着动；父节点缩放，子节点的视觉尺寸整体跟着缩放；父节点旋转，子节点绕着父节点的原点一起转。这个级联关系是 3D 引擎里最基础也最强大的机制，做机械臂、行星系统、人物骨骼挂件全靠它。
坐标系需要单独记一下：Three.js 用的是右手坐标系，Y 轴向上，X 轴向右，Z 轴朝向屏幕外。相机默认看向自己的负 Z 方向，所以把相机放在(0, 0, 5)的位置，它是朝着原点看的。这个“Y 向上”的约定和部分建模软件不一样，导入模型时如果出现“模型躺着”的情况，八成是导出时轴向设置没对上，而不是代码写错了。
还有一个性能相关的细节：每个节点都有matrixAutoUpdate属性，默认是 true，意思是每次渲染前都会根据位置旋转缩放重新计算一次本地矩阵，再向下传递更新世界矩阵。对于大量静态不动的物体，把这个属性关掉可以省下一笔可观的计算，尤其在节点数量上千的场景里效果很明显。我一般在场景搭建完成后统一遍历一遍，把静态物体的这个开关关掉。
2.2 相机选型：透视与正交
相机决定了你看到的画面，选错相机，后面调什么都是别扭的。透视相机模拟人眼，近大远小，适合绝大多数真实感场景、产品展示、空间漫游。它的四个参数是视野角度、宽高比、近裁剪面、远裁剪面。视野角度一般取 45 到 60 度之间，太小画面像长焦压缩，太大边缘会明显变形，超过 75 度就开始有种鱼眼的不适感。
正交相机没有透视缩放，物体远近看起来一样大，这是它的优点也是它的限制。等轴测风格的小游戏、建筑平面示意、2D 与 3D 混合的图表，用正交相机才有那种干净的几何感。我做过一个工业零件的剖面展示，客户明确要求“不要近大远小”，那就是正交相机的主场。
有一个坑必须提前说：近裁剪面和远裁剪面之间的比值不要拉得太夸张。不要出现 near 是 0.001、far 是 100000 这种配置。深度缓冲的精度是有限的，比值过大时会直接表现为模型表面出现斑驳的条纹闪烁，行业里叫 z-fighting。我的经验值是 far 除以 near 控制在 1000 以内，如果场景尺度确实很大，宁可把相机拆成远近两级分别渲染。
| 参数 | 常用取值 | 取值影响 | 踩坑提示 |
|---|---|---|---|
| fov | 45 到 60 | 越大视野越广，边缘变形越明显 | 移动端竖屏建议偏大一点 |
| aspect | 容器宽除以高 | 不跟随容器变化会导致画面拉伸 | resize 时必须同步更新 |
| near | 0.1 左右 | 太大会裁掉近处物体 | 与 far 的比值要控制 |
| far | 依场景尺度定 | 太小远处物体被裁掉 | 场景单位要统一约定 |
2.3 渲染器与动画循环
渲染器负责把场景画出来，创建时最常改的两个选项是抗锯齿和透明背景。抗锯齿开着画面边缘会干净很多，代价是性能开销，低端设备上可以考虑关掉，改用后期处理里的抗锯齿方案。透明背景适合把 3D 画面叠在网页背景上做视觉融合。
颜色空间的设置是近几年最容易被遗漏的一步。贴图有自己的一套颜色编码，渲染输出也有自己的一套，两边没对齐，画面就会整体偏灰或者偏暗。常见的处理方式是：颜色类贴图标记为 sRGB，法线贴图、粗糙度贴图这类数据贴图保持线性，渲染器输出也设置为 sRGB。这一步做对之后，你会明显感觉到材质“活”了过来。
动画循环是让场景动起来的发动机。基本原理是浏览器提供的逐帧回调，每一帧里你更新物体的状态，然后调用一次渲染。这里有两个我强烈建议的习惯：一是用库自带的时间工具去算帧间隔，而不是硬编码每帧固定时间，这样不同刷新率的屏幕上动画速度才一致；二是页面切到后台时暂停循环，浏览器虽然会自动降频，但主动停掉能省电，也避免回来后出现一次巨大的时间跳跃导致动画瞬移。
注意：不要在没有渲染循环的情况下反复手动调渲染函数去做动画，那样既不好控制节奏，也容易在页面隐藏时持续空转消耗资源。
3. 从零跑起第一个可交互场景
理论说再多，不如把一段能跑起来的代码敲一遍。这一节我给出一份完整可用的最小工程，从目录结构到每一行参数为什么这么定都讲清楚。照着做，十分钟内你能在浏览器里看到一个带阴影、能拖拽旋转的立体物体。
3.1 工程结构与依赖引入
目录我习惯分成四层：入口文件、场景构建模块、模型与贴图资源、公共工具函数。哪怕现在只有一个立方体，也建议一开始就按这个结构走，因为 3D 项目的膨胀速度非常快，等你写到第十个物体再重构，成本会翻几倍。
依赖引入有两种常见方式。用包管理器的方式适合正规项目，好处是版本锁定、能配合打包工具做代码分割；用模块映射的方式适合快速试验，一个静态页面就能跑起来，不需要构建步骤。我在做原型验证时首选后者，一个 HTML 文件加一个模块脚本就够，省去一堆配置时间。
<div id="app" style="width:100%;height:100vh;position:relative;"></div> <script type="importmap"> { "imports": { "three": "./node_modules/three/build/three.module.js", "three/addons/": "./node_modules/three/examples/jsm/" } } </script> <script type="module" src="./main.js"></script>这个模块映射把three/addons/前缀指向了官方示例目录，后面引入控制器、加载器时路径会短很多，也不用写一长串相对路径。路径写错的话控制台会直接报模块找不到，比运行起来才白屏要友好得多。
3.2 完整最小代码与逐行解释
下面这段是我常用的起手模板，注释里写明了每个参数为什么这么给。
import * as THREE from 'three'; import { OrbitControls } from 'three/addons/controls/OrbitControls.js'; const container = document.getElementById('app'); // 场景：背景色给一个深色，白色高光更容易看出来 const scene = new THREE.Scene(); scene.background = new THREE.Color(0x11131a); // 相机：fov 给 50，兼顾视野和边缘变形； // near 0.1 / far 200，比值 2000，稍微偏大，后面可以按需收紧 const camera = new THREE.PerspectiveCamera( 50, container.clientWidth / container.clientHeight, 0.1, 200 ); camera.position.set(3, 2.5, 4); camera.lookAt(0, 0, 0); // 渲染器：抗锯齿打开，像素比封顶 2，防止高分屏上像素量爆炸 const renderer = new THREE.WebGLRenderer({ antialias: true }); renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); renderer.setSize(container.clientWidth, container.clientHeight); renderer.outputColorSpace = THREE.SRGBColorSpace; renderer.toneMapping = THREE.ACESFilmicToneMapping; renderer.toneMappingExposure = 1.0; // 阴影：类型选软阴影，视觉上更自然，性能开销中等 renderer.shadowMap.enabled = true; renderer.shadowMap.type = THREE.PCFSoftShadowMap; container.appendChild(renderer.domElement); // 物体：几何体 + 材质 + 网格三件套 const geometry = new THREE.BoxGeometry(1.2, 1.2, 1.2); const material = new THREE.MeshStandardMaterial({ color: 0x4f8cff, roughness: 0.35, metalness: 0.1 }); const cube = new THREE.Mesh(geometry, material); cube.castShadow = true; cube.receiveShadow = true; cube.position.y = 0.6; scene.add(cube); // 地面：只接收阴影，不投射，材质粗糙度给高一点 const ground = new THREE.Mesh( new THREE.PlaneGeometry(20, 20), new THREE.MeshStandardMaterial({ color: 0x22262f, roughness: 0.9 }) ); ground.rotation.x = -Math.PI / 2; ground.receiveShadow = true; scene.add(ground); // 灯光：一个环境光兜底，一个平行光做主光并投射阴影 scene.add(new THREE.AmbientLight(0xffffff, 0.6)); const dirLight = new THREE.DirectionalLight(0xffffff, 2.5); dirLight.position.set(5, 8, 5); dirLight.castShadow = true; dirLight.shadow.mapSize.set(2048, 2048); dirLight.shadow.camera.left = -10; dirLight.shadow.camera.right = 10; dirLight.shadow.camera.top = 10; dirLight.shadow.camera.bottom = -10; dirLight.shadow.camera.near = 0.5; dirLight.shadow.camera.far = 30; scene.add(dirLight); // 控制器：阻尼关掉会显得生硬，开启后拖拽有惯性感 const controls = new OrbitControls(camera, renderer.domElement); controls.enableDamping = true; controls.dampingFactor = 0.08; controls.target.set(0, 0.6, 0); // 尺寸自适应 window.addEventListener('resize', () => { const w = container.clientWidth; const h = container.clientHeight; camera.aspect = w / h; camera.updateProjectionMatrix(); renderer.setSize(w, h); }); // 动画循环 const clock = new THREE.Clock(); renderer.setAnimationLoop(() => { const delta = clock.getDelta(); cube.rotation.y += delta * 0.6; controls.update(); renderer.render(scene, camera); });这段代码里最值得琢磨的是平行光的阴影相机范围。阴影贴图是一张固定分辨率的图，它覆盖的世界范围由这个正交框决定。框给得太大，同样 2048 的贴图摊到大范围上，阴影边缘就会糊成一片；框给得太小，超出范围的物体干脆没有阴影。我的做法是先按场景实际内容量一遍包围盒，框比它大 20% 左右比较合适。
3.3 相机与光照参数的取舍逻辑
相机位置不是随便填的。我一般用一个简单的方法确定：先估出物体的最大外接球半径 r，相机到目标点的距离取 r 的 2.5 到 3 倍，再用视野角度反推。具体算法是，需要的水平半视角 θ 满足 tan(θ) = r / d，而相机水平半视角约等于 fov 的一半乘以宽高比修正。如果算出来物体还是被裁掉，优先调距离而不是狂调 fov，因为 fov 拉大带来的是透视畸变，看着很难受。
光照这块，物理单位的变化是近几年最大的迁移坑。较新的版本里，光的强度不再是一个可以随便给 0.1、0.2 的相对值，而是偏向物理单位的量，给 1 已经偏弱，平行光给到 2 到 4 很常见。很多老教程里写new THREE.DirectionalLight(0xffffff, 0.5)，新版里跑出来几乎一片黑，不是代码坏了，是量纲变了。
材质方面，如果需要金属感或者真实反射，光靠平行光是不够的，必须给场景一个环境贴图。最省事的做法是用官方示例里提供的环境纹理生成器，把一个内置的室内环境烘焙成环境贴图，赋给场景的环境属性。这一步做完，金属材质立刻从“灰塑料”变成“有反射的金属”，反差非常大。
3.4 尺寸适配与高分屏处理
响应式这块有两个地方容易漏。一是相机宽高比没有跟着更新，画面会被横向或纵向拉伸，表现为球看起来是个椭圆；二是渲染器的尺寸没有同步，画面模糊或者只占容器一角。两处必须一起改，而且改完相机要调一次投影矩阵更新，否则改了参数不生效。
像素比的处理是我踩过最多次的坑。高分屏上设备像素比可能是 2 甚至 3，直接照搬意味着渲染的像素量是逻辑像素的四倍到九倍，帧率断崖式下跌。封顶在 2 是业内比较通行的折中，视觉上已经足够细腻，性能也不会失控。如果用户设备明显偏弱，可以进一步降到 1.5。
提示：容器尺寸用
clientWidth而不是offsetWidth，后者包含边框，会导致画面被计算得偏大一点点，长期看会造成轻微错位。
4. 模型加载、交互控制与动画
真正干活的时候，场景里很少是基础几何体，多数是从外部导入的模型。这一环涉及格式选择、解码器配置、材质覆盖、坐标系对齐，是新手翻车率最高的地方。我把这部分单独拆出来讲透。
4.1 模型格式选择与加载流程
格式上，我基本只用 glTF 的二进制版本。原因是它是为实时渲染设计的，几何、材质、贴图、动画、骨骼打包在一个文件里，解析快，官方加载器支持最完整。其他格式在别的软件里可能是主力，但转到 Web 场景时往往要多一道转换，中间容易丢材质或丢动画。
加载流程有几个固定动作。第一，创建统一的加载管理器，把所有资源的进度汇总成一个百分比，前端显示加载条才有意义。第二，配置压缩扩展对应的解码器，很多模型为了减小体积会做几何压缩，不配解码器会直接加载失败，报错信息里通常能看到扩展名的关键字。第三，加载完成后的回调里做三件事：设置阴影投射与接收、按包围盒自动缩放到合适尺寸、把模型放到底面贴地的位置。
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js'; import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js'; import { LoadingManager } from 'three'; const manager = new LoadingManager(); manager.onProgress = (url, loaded, total) => { console.log(`加载进度 ${loaded}/${total}`); }; const draco = new DRACOLoader(manager); draco.setDecoderPath('./decoders/draco/'); const loader = new GLTFLoader(manager); loader.setDRACOLoader(draco); loader.load('./assets/model.glb', (gltf) => { const model = gltf.scene; // 统一遍历设置阴影 model.traverse((child) => { if (child.isMesh) { child.castShadow = true; child.receiveShadow = true; } }); // 按包围盒自适应缩放到目标尺寸，避免模型单位五花八门 const box = new THREE.Box3().setFromObject(model); const size = box.getSize(new THREE.Vector3()); const maxSide = Math.max(size.x, size.y, size.z); const targetSize = 2; const scale = targetSize / maxSide; model.scale.setScalar(scale); // 重新计算包围盒，把模型底面贴到 y = 0 const box2 = new THREE.Box3().setFromObject(model); model.position.y -= box2.min.y; scene.add(model); }, undefined, (err) => { console.error('模型加载失败', err); });这段自适应逻辑值得单独强调。不同建模人员导出的模型单位差别巨大，有的是毫米，有的是米，不做归一化处理，你会发现模型要么小得看不见，要么大到把相机包在里面，屏幕上什么都看不到，还以为是代码坏了。用包围盒做一次归一化，后面所有相机、灯光、地面的参数才能稳定复用。
4.2 交互控制与事件拾取
轨道控制器是标配，几行代码就能实现拖拽旋转、滚轮缩放、右键平移。有几个参数我几乎每次都会调：开启阻尼让停手后有缓动，设置最小和最大距离防止用户把相机推进物体内部或者拉到看不见，限制垂直旋转角度避免翻转到底部出现天地颠倒的观感，禁用右键菜单避免和浏览器默认行为冲突。
除了相机交互，另一类需求是点选物体。原理是从相机位置向鼠标位置发一条射线，和场景里的物体求交，拿到最近的那个。这中间有个坐标换算的坑：鼠标坐标要转换到标准化设备坐标，也就是把左上角为原点的像素坐标映射到 -1 到 1 的区间，Y 轴还要翻转。这一步算错，表现就是“点击位置和选中物体总是错开一段距离”，很多人查半天以为是模型问题。
const raycaster = new THREE.Raycaster(); const pointer = new THREE.Vector2(); renderer.domElement.addEventListener('pointerdown', (e) => { const rect = renderer.domElement.getBoundingClientRect(); pointer.x = ((e.clientX - rect.left) / rect.width) * 2 - 1; pointer.y = -((e.clientY - rect.top) / rect.height) * 2 + 1; raycaster.setFromCamera(pointer, camera); const hits = raycaster.intersectObjects(pickables, false); if (hits.length > 0) { console.log('选中了', hits[0].object.name); } });注意这里用的是元素自身的包围矩形，而不是窗口尺寸。如果 canvas 不是铺满全屏，而是嵌在某个侧边栏里，用窗口尺寸算出来的坐标会整体偏移。这个细节在布局复杂的页面里特别关键。
4.3 动画组织与帧率无关写法
动画代码最常见的错误是把时间写死。比如每帧旋转 0.01 弧度，在 60 赫兹屏幕上是一秒 0.6 弧度，在 120 赫兹屏幕上就变成 1.2 弧度，速度直接翻倍。正确做法是拿帧间隔乘以速度系数，这样任何时候速度都一致。
对于多段动画，我习惯用一个很小的调度结构：把每个动画写成一个接收时间参数的函数，放进数组，循环里统一遍历执行。好处是加一个新动画只要往数组里推一个函数，不用改循环体。如果涉及模型自带的骨骼动画，用官方的动画混合器播放，记得每帧调用一次更新并传入帧间隔，否则动画不会推进。
const actions = [ (t) => { cube.rotation.y = t * 0.6; }, (t) => { cube.position.y = 0.6 + Math.sin(t * 1.5) * 0.15; } ]; const clock = new THREE.Clock(); let elapsed = 0; renderer.setAnimationLoop(() => { const delta = clock.getDelta(); elapsed += delta; actions.forEach((fn) => fn(elapsed)); controls.update(); renderer.render(scene, camera); });另外别忘了资源释放。单页应用里反复创建销毁场景，几何体、材质、贴图、渲染目标都占着显存，不主动释放，来回切几次页面内存就上去了。释放的写法是遍历场景，对几何体、材质、贴图分别调释放方法，渲染器本身在彻底不用时也要调。
5. 性能优化与排查实录
3D 页面最怕的不是功能做不出来，而是做出来之后在用户的机器上卡成幻灯片。性能问题有个特点：只看代码看不出来，必须看数据。所以我第一步永远是打开渲染器自带的信息对象，看每帧的绘制调用数和三角形数量，这两个数字基本能定位问题的大方向。
5.1 关键指标与优化手段
绘制调用数是重中之重。每一次材质切换、每一个独立网格，都可能产生一次绘制调用。几百次在桌面端还能扛，移动端就开始掉帧。优化的核心思路是合并：相同材质的静态物体用几何合并工具合成一个网格；大量重复的小物体用实例化网格，一次绘制画出成百上千个；贴图尽量合到一张图集里，减少材质数量。
| 优化方向 | 具体做法 | 适用场景 | 预期收益 |
|---|---|---|---|
| 减少绘制调用 | 几何合并、实例化网格 | 大量重复物体 | 高 |
| 降低填充压力 | 像素比封顶、减小画布 | 高分屏、移动端 | 高 |
| 阴影优化 | 缩小阴影相机范围、降低贴图分辨率 | 阴影明显的场景 | 中高 |
| 纹理优化 | 压缩纹理、按需降分辨率 | 贴图多、体积大 | 中 |
| 层级细节 | 远近切换不同精度模型 | 大场景、远景多 | 中 |
| 剔除 | 开启视锥剔除、手动隐藏不可见物体 | 视野外物体多 | 中 |
实例化这块值得展开说。场景里要放三百个相同的小立方体，逐个创建网格就是三百次绘制调用，改成实例化网格之后是一次。做法是创建实例化网格时指定最大数量，然后循环往每个实例的变换矩阵里写入位置、旋转、缩放，写完标记需要更新。这个技巧在数据可视化里特别好用，比如用高度不同的小柱子表达一堆数值。
阴影是第二个吃性能的大户。很多人一上来就开 4096 的阴影贴图，结果帧率直接腰斩。实际上阴影贴图的收益有个明显的边际递减，从 1024 提到 2048 是肉眼可见的提升，从 2048 提到 4096 在多数场景里几乎看不出来，但开销翻倍。我的默认值是 2048，同时把阴影相机的范围收紧到只覆盖主要内容区域。
注意：调试性能一定要在真机上验证。桌面浏览器的高性能显卡会掩盖绝大多数问题，等到在手机上打开才发现卡，返工成本很高。
5.2 常见问题速查
下面这张表基本覆盖了我这些年被问得最多的症状，照着排查能解决八成问题。
| 症状 | 最可能原因 | 排查动作 | 解决方式 |
|---|---|---|---|
| 页面全黑但无报错 | 相机位置在物体内部或朝向反了 | 打印相机位置，把物体换成一个巨大球体测试 | 调整相机位置并调用朝向目标 |
| 物体是纯黑剪影 | 材质需要光照但场景没有光源 | 临时加一个环境光看是否变亮 | 补光源或改用不受光材质 |
| 模型加载 404 | 路径错、服务器未配置该扩展名 | 看网络面板的状态码 | 修正路径、检查静态资源配置 |
| 模型全黑或全白 | 材质贴图丢失、颜色空间不对 | 检查材质贴图引用、看颜色空间设置 | 重新导出模型、校正输出设置 |
| 模型巨大或极小 | 导出单位不一致 | 打印包围盒尺寸 | 按包围盒归一化缩放 |
| 模型是躺着的 | 轴向约定不同 | 观察模型朝向 | 绕 X 轴旋转负 90 度修正 |
| 表面有条纹闪烁 | 近远裁剪面比值过大 | 检查相机 near 与 far | 收紧范围或分层渲染 |
| 拖拽旋转没反应 | 控制器绑定的元素不对 | 确认绑的是渲染画布 | 改为绑定渲染器的画布元素 |
| 画面被拉伸成椭圆 | 宽高比未随容器更新 | 缩放窗口观察 | 尺寸变化时同步更新相机 |
| 移动端帧率极低 | 像素比过高、阴影过重 | 看渲染信息里的绘制次数 | 封顶像素比、降阴影精度 |
| 切换页面后内存持续上涨 | 资源未释放 | 反复进出观察内存曲线 | 遍历释放几何、材质、贴图 |
| 纹理颜色发灰 | 颜色空间标记错误 | 对比贴图原图与渲染结果 | 颜色贴图标记为 sRGB |
5.3 几个只有踩过才知道的细节
第一个，模型自带的材质有时候会成为性能黑洞。有些导出文件里每个零件一个独立材质，几百个材质意味着几百次状态切换。我在实际项目里的做法是加载完成后遍历一遍，把材质按颜色和粗糙度归类，能共用的就替换成同一个材质实例，绘制调用数往往能降一个数量级。
第二个，透明材质要慎用。大量半透明物体叠加时，深度排序会变得很麻烦，容易出现“后面的物体挡住前面的”这种视觉错误，而且透明度混合本身有填充率开销。如果只是想要一个淡淡的玻璃感，考虑用带反射的不透明材质加一点环境贴图来伪造，比真透明稳得多。
第三个，动画循环里的对象创建是大忌。每一帧都 new 一个向量、new 一个颜色，垃圾回收会周期性地卡一下，表现为规律性的顿挫。解决办法是把临时对象提到循环外面复用，用对象的设置方法去改值而不是新建。
第四个，模型文件本身该瘦身。几何压缩、贴图压缩、删掉看不见的内部结构、合并重复材质，这几步做完，一个 20 MB 的文件压到 3 MB 以内很常见。首屏加载时间对留存的影响非常直接，这一步的投入产出比往往比代码层面的优化还高。
6. 项目结构组织与工程化落地
写到中后期，代码组织的重要性会超过技术细节。我见过太多项目把所有逻辑塞进一个文件，最后两千多行，改一个颜色要滚半天，加一个物体要在五个地方同步修改。趁早分层，后面会轻松很多。
6.1 推荐的分层方式
我的习惯是按职责切成几块：核心层负责场景、相机、渲染器、循环的初始化与销毁；对象层负责创建和管理具体的物体、模型、灯光组；交互层负责控制器、拾取、UI 事件；工具层放通用的归一化、性能监测、资源释放函数。各层之间只通过明确的接口通信，比如核心层提供一个添加物体的方法，对象层调它，而不是互相直接引用私有变量。
这种切法最直接的好处是可测试和可复用。换一个项目，核心层和工具层原样带走，只重写对象层和交互层，起手速度快很多。另外把配置项抽成一个独立的对象也很值得，相机距离、灯光强度、背景色这些参数集中管理，调视觉的时候改一处就行，不用满项目搜索。
6.2 资源管理与发布前的检查单
发布前我有一份固定检查单，逐条过一遍能挡掉大部分线上事故。清单包括：所有外部资源路径改成相对路径或确认 CDN 可达；模型和贴图开启压缩并确认解码器路径正确；低端设备降级策略生效；页面隐藏时动画循环暂停；窗口尺寸变化时相机与渲染器同步更新；离开页面时资源释放；首屏加载有进度提示；控制台没有任何警告。
还有一点容易被忽略：加载失败的兜底。模型加载不到的时候，页面上不能是一片空白，至少要给一个占位几何体或者明确的错误提示。我在一个对外展示的项目里就吃过这个亏，某个网络环境下模型请求一直失败，用户看到的是一个空空如也的深色背景，完全不知道发生了什么，后来加了兜底物体和提示才把体验补回来。
真正把 Three.js 用顺手之后你会发现，它难的从来不是 API，而是对三维空间的那点直觉：相机放在哪、光从哪个方向来、这个尺寸合不合理。这些东西没有捷径，就是多搭多看。我自己的习惯是每学一个新特性，就打开官方示例页面对照着改参数，看画面怎么变，比读十遍文档都管用。踩过的坑也别急着删，记在本子上，下次遇到同样的症状，翻一眼就能省下半天时间。
