Three.js 版本升级注意事项：API 变动与兼容性处理

Three.js 并不遵循语义化版本号（SemVer），而是采用每月迭代一次的 rXXX 单调累加发版机制。这就意味着任何次级版本的跃迁，都可能伴随着几何体结构、色彩空间、渲染衰减模型以及模块解析路径的破坏性变动。本文直面工程升级中的真实痛点，拆解核心变动脉络，并给出循序渐进的兼容升级与故障排查方案。

一、版本迭代特征与升级前置准备

在启动升级工作前，必须先认清 Three.js 的版本迭代特性。官方不会因为移除了核心类而发布一个“主版本号 2.0”，而是将重大破坏性重构直接分配在 r125、r150 或 r160 等普通版本中。通常，核心团队会在变更发生前 5 到 15 个版本在浏览器控制台中打印带有堆栈的废弃警告（Deprecation Warning），并在宽限期结束后直接物理删除废弃 API。

因此，针对已有生产级 3D 应用的版本升级，严禁一次性从如 r110 直接硬跳到 r165+。跨度过大将导致数十个不同时期的破坏性变更并发，使得报错信息相互掩盖，极大增加排查难度。正确的工程实践是以 10 到 15 个版本为一个步进梯度，逐级消除废弃警告后再迈向下一阶段。

二、核心破坏性 API 变动与代码迁移对照

梳理近几十个版本的历史提交，阻断升级或导致画面渲染异常的改动高度集中在四大领域：几何体数据结构的统一、色彩空间管理的重塑、物理光照衰减的强制规范，以及官方扩展加载路径的收敛。

1. 几何体体系：从 Geometry 全面转向 BufferGeometry

在 r125 之前，Three.js 并存着两套网格数据结构：友善易读但性能低下的 THREE.Geometry（内部为 Vector3 顶点对象数组与 Face3 面数组），以及直接映射 GPU 显存连续内存块的 THREE.BufferGeometry。由于 THREE.Geometry 在提交绘制前必须在 CPU 端做一次重量级的隐式转换，官方在 r125 中将其彻底移除。

如果代码中包含动态生成多边形、地形高度计算或自定义顶点编辑，旧代码在新版中会抛出 TypeError: THREE.Geometry is not a constructor 阻断性异常。必须改写为类型化数组（Float32Array）并显式挂载 BufferAttribute：

// 🔴 遗留方案 (r125 之后彻底失效报错)
const geometry = new THREE.Geometry();
geometry.vertices.push(
  new THREE.Vector3(-1.0, -1.0,  1.0),
  new THREE.Vector3( 1.0, -1.0,  1.0),
  new THREE.Vector3( 1.0,  1.0,  1.0)
);
geometry.faces.push(new THREE.Face3(0, 1, 2));
geometry.computeFaceNormals();

// 🟢 现代规范方案 (所有现代版本通用)
const geometry = new THREE.BufferGeometry();
const vertices = new Float32Array([
  -1.0, -1.0,  1.0,
   1.0, -1.0,  1.0,
   1.0,  1.0,  1.0
]);
// 每 3 个浮点数组成一个 3 维顶点向量
geometry.setAttribute('position', new THREE.BufferAttribute(vertices, 3));
// 显式计算顶点法向量以支持受光
geometry.computeVertexNormals();

2. 色彩空间管理：outputEncoding 到 outputColorSpace

在 r152 之前，Three.js 使用 outputEncoding 与 THREE.sRGBEncoding 进行输出色彩编码管理。这套机制在处理包含 glTF 模型、自定义贴图和后处理管线时极易出现双重伽马校正（Double Gamma Correction），导致画面泛白发灰或暗部被过度压暗。

现代 Three.js 引入了符合行业标准的 ColorManagement 体系。核心渲染器的输出属性变更为 outputColorSpace，并且常量更名为 THREE.SRGBColorSpace（而非旧的 sRGBEncoding）。漫反射贴图（map）必须显式标记其色彩空间，而法线、金属度、粗糙度等数据贴图则必须保持无色彩空间转换（NoColorSpace）：

// 🔴 遗留写法 (r152 后废弃并移除)
renderer.outputEncoding = THREE.sRGBEncoding;
texture.encoding = THREE.sRGBEncoding;

// 🟢 现代规范方案 (r152 及更高版本)
renderer.outputColorSpace = THREE.SRGBColorSpace;

// 漫反射/颜色贴图必须显式声明 sRGB 空间
const diffuseMap = textureLoader.load('diffuse.png');
diffuseMap.colorSpace = THREE.SRGBColorSpace;

// 数据型贴图（法线、粗糙度、粗糙度金属度通道）严禁设置 SRGBColorSpace！
const normalMap = textureLoader.load('normal.png');
normalMap.colorSpace = THREE.NoColorSpace; // 保持线性数据原貌

3. 光照衰减物理化：useLegacyLights 的终结

许多开发者在把项目从 r140 升级到 r155+ 后，最明显的现象就是场景突然变得“全黑”或者“极度昏暗”。这是因为早期的 Three.js 默认采用艺术调光算法，点光源和聚光灯没有按照真实的物理平方反比定律衰减。

在 r150 版本中，官方引入了 renderer.useLegacyLights = true 作为过渡开关，并在 r155 彻底删除了该开关，默认全面切换为物理正确光照（Physical Light Units）。在物理模式下，点光源的默认衰减系数 decay 为 2，光源强度的度量单位由原本无物理意义的标量变成了坎德拉（Candela）或流明（Lumen）。

升级到现代版本后，原来设置为 intensity = 1.0 的点光源，其照度通常需要提高数十倍甚至数百倍（例如调整至 intensity = 50 或乘以 Math.PI），才能达到与旧版本相似的视觉明暗。

4. 模块导入路径：three/addons 的原生化

在早期的 npm 工程中，导入官方扩展类（如 OrbitControls、GLTFLoader）需要穿透到深度相对路径：

// 🔴 易碎的深层文件路径
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';

在 r147 之后，Three.js 规范了其 package.json 的 exports 字段，并正式将 three/examples/jsm/ 映射为标准子路径 three/addons/。现代构建工具（如 Vite、Webpack 5、Rollup）均能原生解析该路径：

// 🟢 规范推荐的子路径导入
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

三、周边扩展库（Addons）与资源加载兼容性

Three.js 的生态架构决定了其“核心库”与“扩展库（examples/jsm 或 addons）”是严格同源发布的。与一些三方组件库不同，Three.js 的官方扩展没有单独的发版周期。这一机制在工程中常常引发以下隐患：

• 依赖分裂与多实例（Duplicate Instances）：如果主工程安装了 three@0.160.0，而引入的某个三方库（如某个后处理效果库或图表组件）依赖了 three@0.145.0，打包工具可能会打出两份 Three.js 核心代码。这会导致 instanceof THREE.BufferGeometry 或 instanceof THREE.Material 判定为 false，从而在渲染器内部默默忽略网格或直接崩溃。
• OrbitControls 的 DOM 挂载要求：旧版中 new OrbitControls(camera) 会隐式监听 document，而在现代版本中，构造函数强烈要求显式传入 renderer.domElement：new OrbitControls(camera, renderer.domElement)，否则在存在页面其他交互组件时会引发捕获冲突。
• 带骨骼模型的深度克隆：若使用 model.clone() 复制一个包含骨骼动画的 SkinnedMesh，新旧模型会错误地共享同一套骨架变换。升级现代版本后，必须从 three/addons/utils/SkeletonUtils.js 引入 SkeletonUtils.clone(model) 进行深层骨骼克隆。

四、升级常见典型故障与快速排查

版本升级后若出现异常，通常不需要盲目回滚，按下列现象进行针对性排查即可快速定位根因：

异常表现	典型触发原因	修复处置动作
场景整体昏暗或全黑	物理光照 Decay 默认为 2，旧点光源强度不足	将点光源与聚光灯 intensity 提高 20~100 倍；检查环境贴图 scene.environment
材质发白或色彩严重泛灰	色彩空间未对齐，纹理未设置 SRGBColorSpace	将渲染器 outputColorSpace 设为 SRGBColorSpace，颜色贴图统一标记 colorSpace
TypeError: Geometry is not a constructor	r125 彻底移除了 THREE.Geometry 类	改用 THREE.BufferGeometry，顶点数据转为 Float32Array
Module not found: three/examples/jsm/...	构建工具未正确解析旧路径或缺少扩展后缀	改用 three/addons/... 语法，并确保导入路径末尾保留完整的 .js 扩展名
模型骨骼动画克隆后无法播放	直接调用 Mesh.clone 导致骨架与蒙皮解绑	使用 SkeletonUtils.clone(gltf.scene) 替代原生 clone 方法

五、升级自检与质量防护矩阵

为了确保升级后的工程具备长期可维护性与稳定性，应当在合并分支前依据下方矩阵逐项核查。

在完成上述所有清单的核对后，最后一步是在开发控制台中开启所有级别的日志输出，确认没有出现任何黄色的 THREE.WebGLRenderer: ... has been deprecated/removed 警告信息。保持控制台“零警告”是项目未来平滑过渡到下一个大版本的最有效保障。