Three.js 版本升级与 Breaking Change 治理:r100 至今的迁移代价 Three.js Version Upgrade & Breaking Change Governance
r 编号是日历不是承诺 · Breaking Change 按玩家可见度分三级 · 三种锁定策略与 ^0.x 的骗局 · 视觉回归探针清单 · 灰度与一键回滚
版本治理:唯一一个你什么都不做也会找上你的决策
先说个真事。去年有个朋友拽我救火,他的团队在做一款 Web 3D 的岛屿经营游戏,demo 的招牌镜头是傍晚六点、太阳压到海平线那一刻,水面反射把整片岛染成橘色。上线前两个月,组里有人随口提了一句:“three 升个版本吧,现在这个有点老。”他们花了一个下午升级,跑起来,控制台干干净净,一个红字都没有。
但你猜怎么着——傍晚六点的海面,反光没了。整个岛像被人从摄影棚搬到了阴天。接下来三天,美术在骂,程序在查,策划在业主群里问“是不是谁把 HDR 换了”。最后定位到:光照强度的单位变了。他们一行渲染代码都没动过。
这个故事的重点不是“升级有风险”这种废话。重点是:在你什么都没改的情况下,你的画面变了。放在传统游戏行业里这是件很离谱的事——你不会接受引擎悄悄把你的美术资源改样。但在 Three.js 生态里,这是每个月都可能发生的日常。它发布的频率是“月”,你项目的节奏是“季度”和“年”,两个时间尺度撞在一起,摩擦是必然的。
所以这一篇我放在系列的治理位,想说的其实是:版本管理不是你项目末尾的运维杂活,它是第一块基石。因为别的决策(用不用 PBR、上不上后处理、走不走 WebGPU)都是“你选的”,只有版本这件事,是“它会来找你”的。你不理它,它就替你更新世界观。
顺带说清楚本文的边界:我不打算复述官方更新日志,那玩意儿你可以自己翻。我想给你的是三样东西——一套能把 Breaking Change 分级的判断方法,一张能把“升不升”变成可算的配置表,一条能让升级不再是赌博的流水线。这三样凑齐了,你团队里那个“懂渲染的人”就不用每次发版都心跳加速。
第一层:r 编号不是版本号,是日历
第一个认知得掰正。看到 r170、r180 这种编号,绝大多数人的大脑会自动套用“大版本.中版本.补丁”的模板,然后默认“同一个大版本内是安全的”。这个直觉在 Three.js 上会害死你。
r 后面的数字,本质上是第几次月度发布。它没有主次之分,r169 和 r170 之间可以删掉半个模块,r170 和 r171 之间也可能风平浪静。编号只回答“这是第几次”,不回答“这次安不安全”。
有意思的是,从 npm 的规则上讲,Three.js 还真没违约。它在 npm 上的版本号是 0.x.y 的形式,而在语义化版本(SemVer)的定义里,主版本号为 0 意味着“任何变化都可能是破坏性的,使用者自担风险”。换句话说,它从来没签过那份“兼容性合同”,自然也就谈不上毁约。这不是钻空子,这是一个明确的治理选择:用快速删旧 API 来逼整个生态保持现代,代价由使用者承担。
官方的破坏性变更节奏也印证这一点:先把某个 API 标记为弃用,运行时在控制台打警告,保留一到两个版本(也就是一到两个月),然后删掉。对 Three.js 来说,半年前的写法就已经算“化石”了。你项目的迭代周期如果是三个月一个里程碑,那你的每一次升级都是跨时代的。
拿同领域另一个库做对照,差异会非常刺眼。Babylon.js 走的是标准的大版本路线,从 5.0 到 6.0 到 7.0 再到 8.0,每个大版本之间有小版本,大版本发布时配一份专门的迁移指南,把“哪些 API 没了、替代写法是什么、行为哪里变了”列成清单。一个用 6.x 写的项目,在 6.x 里随便升,几乎不会出问题;要跨到 7.0,你读那份指南就行。这套东西的本质不是技术高明,是把“破坏”这件事集中、预告、文档化。
而 Three.js 把破坏均摊到了每一个月里。它这么做有它的道理——没有商业公司养着,靠社区提交驱动,月度发布是维持活力的方式,快速清理旧代码能防止整个库腐化成一个不敢动的泥潭。但这笔账的另一半,转移到了像你我这样把 Three.js 当引擎用的游戏团队身上:Three.js 是渲染库,不是引擎。你把它当引擎用,就得自己补上引擎该有的那层“版本契约”。
这句话值得你抄在便签上。因为后面所有的方法论,都是在替它打工。
第二层:Breaking Change 按玩家可见度分三级
“破坏性变更”这个词太笼统了。把一堆变更丢进一个筐里,你的团队就没法排优先级。我习惯按玩家能不能看见和你能不能马上发现这两个维度切成三类。
| 级别 | 玩家/开发者看到什么 | 典型场景 | 发现难度 | 修复成本 | 建议处理方式 |
|---|---|---|---|---|---|
| A 类:加载期报错 | 白屏、控制台红字、模块 404 | API 改名、模块路径改写、附属文件被删 | 极低,第一次刷新就知道 | 低,批量替换 | 一次性清完,控制在一天内 |
| B 类:静默行为变更 | 不报错,但画面、手感、参数含义变了 | 色彩空间、光照强度单位、阴影偏移语义、贴图朝向 | 极高,可能一周后美术才发现 | 高,要重调美术参数 | 升级前必须先建视觉基线 |
| C 类:管线级重构 | 大范围重写,整个渲染路径换血 | 着色器体系迁移、渲染入口拆分、后端换代 | 中,一读文档就明白躲不过 | 极高,按“项目”算 | 单独立项,别混在日常迭代里 |
说句实话,A 类是朋友,B 类是亲戚——报错的 bug 会自己找上门让你五分钟修好,不报错的 bug 住你家、吃你饭、还装作没事。
案例深挖一:色彩空间的那一刀(r152 前后)
这是 r100 之后最疼的一刀,没有之一。改动前,项目里给一张贴图标上 sRGB 编码,渲染器输出也标上 sRGB 编码,颜色基本上是“你写什么就显示什么”,闭环但物理上是错的。改动后,颜色管理默认开启:所有颜色在内部按线性空间参与运算,只在最后一步转回显示空间。
物理上这是巨大进步——光的叠加本来就是线性的,只有在线性空间里做光照、做混合、做景深,结果才站得住。但代价是:所有已经调好的项目,色相、明度、对比度全部平移了一次。
玩家实际会体验到什么?我列几个真实的症状。你在代码里写死的一个琥珀色,突然变得又亮又艳,因为你以为的十六进制值现在被当成了显示空间的颜色再转线性,一步之遥,结果全变。带自发光的霓虹材质和后处理里的泛光效果会彻底错位——泛光的阈值是按旧亮度手调的,现在要么整片糊成一块光斑,要么干脆一点光晕都没有。美术最抓狂的是贴图:以前忘记标色彩空间是“无所谓”,现在是“暗部全糊成一片黑”。
官方为什么非干不可?因为整个 PBR 材质体系(本系列第 02 篇讲的那套 roughness/metalness 工作流)和光照模型(第 14 篇讲的 Cook-Torrance 那一路)在数学上都默认一件事:光强是线性的。你把非线性编码的颜色喂进去,粗糙度调得再准,反射也是错的。所以这一刀不是折腾人,是补上早该补的课。
但它揭示了一个结构性矛盾:正确性和已发布资产之间,Three.js 永远选正确性。因为它服务的是“未来所有新项目”,不是“你那个已经在跑的项目”。明白这一点,你就知道该怎么规划升级节奏了。
案例深挖二:光照单位换了,你的夜景直接黑掉(r155 前后)
这一刀比上一个更阴。以前光照是“任意单位”,你在场景里放一个强度为 1 的点光源,看起来是个亮度合理的灯泡。后来物理正确的光照成为默认:点光源和聚光灯的强度按物理单位算,衰减严格按距离平方走。
结果就是:所有点光源暗了一个数量级。夜景从“有氛围的暗”变成“伸手不见五指”,白天场景里那些靠补光提亮的小角落全塌了。很多团队的处理方式是给所有点光强度乘一个系数,经验值大概在 12 到 13 附近(背后是球面全向辐射的 4π 那笔账),但这不是万能公式。因为真正决定这个系数的是你场景的物理尺度——如果你的世界里 1 个单位代表 10 米,那换算关系完全不同。
再往下挖一层,会挖出个更根本的问题:Three.js 没有“场景尺度”这个概念,但物理光照必须有。这是一个纯系统设计问题,不是一个参数问题。你得自己立规矩:全项目约定 1 单位等于 1 米。定了这个约定之后,灯的强度、相机的近远裁面、雾的密度、粒子的大小、物理引擎的重力、音频衰减距离,全部要遵守它。这条约定不立,你每次升级都会在不同的地方被同一件事绊倒。
案例深挖三:附属文件消失(r148 前后)
这一刀是纯 A 类,但杀伤面大得离谱。老写法是:网页里用 script 标签直接引一个打包好的 three 文件,再引一个控制器的附属脚本,然后在全局对象上拿东西用。后来这条路被彻底砍掉,只保留 ES Module,附属模块要走新的别名路径,需要 import map 或者打包器。
玩家看到的是什么?白屏加 404。而死在这条刀下的,往往是最没有维护能力的那批项目:3D 商品展示页、H5 互动、个人作品集。这类东西通常一次性交付,代码躺在某台服务器上三年没人碰。这一刀下去,它们直接被从互联网上抹掉。
我自己就翻过这个车。有个两年前做的小 demo 就是这个写法,去年我想打开改点东西,白屏。第一反应是“我是不是记错路径了”,折腾了半小时才反应过来压根不是我的问题。那种感觉就像回家发现钥匙孔被人换了个形状。
第三层:三种锁定策略,以及一个骗了很多人的 ^ 号
聊策略之前,先拆一个几乎人人都踩过的坑。很多人以为在依赖清单里写一个带 ^ 前缀的版本号,就等于“跟着社区走,自动吃小更新”。在常规的语义化版本里这没错,但在 0.x 版本上,脱字符只允许补丁位变化。
也就是说,写成 ^0.160.0,实际允许的范围是 0.160.0 到 0.161.0 之前。主版本号是 0 的时候,语义化规则认为“任何变化都可能是破坏性的”,所以它根本不给你跨小版本的自由。我见过不止一个团队,依赖清单里写着 ^,团队共识是“我们跟随最新”,实际上钉死在一年多前的版本上。然后他们还在论坛上困惑:“你们说的那些新版问题我怎么从来没遇到?”你当然没遇到,你没升。
这个坑的教训不是“别用 ^”,而是你连自己处在哪条策略上都没搞清楚,就已经在承担这条策略的代价了。
| 策略 | 具体做法 | 升级频率 | 一次性代价 | 累积风险 | 适合的项目阶段 |
|---|---|---|---|---|---|
| 全钉死 | 写精确版本号,锁文件提交进仓库,永不主动升 | 几乎为零 | 零 | 高,且是“某天集中还债”型 | 已上线进入维护期、一次性站点、Game Jam 原型 |
| 紧跟最新 | 每发一个新版本就升 | 每月 | 小但持续 | 中,永远在处理小摩擦 | 长期运营、有专职渲染岗、技术本身就是卖点 |
| 巡航(推荐) | 每 8 到 12 周开一个升级窗口,单次跨 3 到 5 个版本 | 每季度 | 中等,可预算 | 低 | 绝大多数商业项目的甜点区 |
我推荐巡航,理由很朴素:一次跨 3 到 5 个版本,是“人还能读懂迁移成本”的上限。跨 20 个版本,你面对的不是一份变更列表,是一份考古报告,你得靠猜中间发生了什么。跨 1 个版本,你又会被琐碎的细节淹没,投入产出比极差。
案例深挖:HexGL——一块跑得动、但改不动的琥珀
HexGL 是 2013 年前后非常有名的网页竞速游戏,作者是 Thibaut Despoulain,用 Three.js 做的反重力赛道飞行,在当年那个 WebGL 还很稀罕的年代,画面表现相当惊艳,被大量文章引用过。我去翻过它的仓库,Three.js 是以打包好的单个文件形式直接塞进项目里的,版本号写在文件头注释里。这是那个年代 Web 项目的标准操作。
这个选择的收益非常明确:十年过去,它依然能跑。它完全不受十几年来任何一次破坏性变更的影响,因为它从来就没打算跟版本走。对于一件“我已经做完、只想让它继续存在”的作品,这是正确决策。
代价同样明确:它基本失去了继续生长的能力。你想给它加个现代 PBR 材质,或者接一套新的后处理,你会立刻发现底层的 API 体系已经不是同一回事了。它成了一件琥珀里的标本——好看,但里面的生物体再也不会动了。
这个案例真正要说的不是“钉死是错的”,而是:钉死是一笔用未来换现在的交易,你得清楚自己在买什么。一次性小游戏、营销活动页、课程作业,钉死完全正确,甚至是最优解。但一个计划活三年的项目,钉死等于给未来的自己埋了一颗定时炸弹,而且这颗炸弹的引信是由“你什么时候需要新特性”决定的,你控制不了。
案例深挖:A-Frame——越往上抽象,越必须焊死底层
对照另一个例子。A-Frame 是 Mozilla 那套用 HTML 标签描述 3D 场景的 WebXR 框架,它的地基就是 Three.js。它怎么做版本治理?把 Three.js 钉死在一个具体版本上,不跟。
为什么?因为 A-Frame 自己有一层承诺:用我写的这套声明式标签,能稳定跑。如果底下三个月一换地基,那 A-Frame 团队就得每个月重写一次适配层,而它的用户会永远在踩那些本来不该他们操心的坑。钉死底层,是它对自己用户负责的方式。
这一条我建议你反复咂摸:你的游戏,就是站在 Three.js 之上的那一层抽象。你对你自己的美术、你自己的关卡设计师、半年后回来改 bug 的你自己,有承诺义务吗?有。因为你手里那些已经调好的材质球、已经布好光的场景、已经对齐的特效时间轴,都是“已经发布的资产”,它们比版本号重要得多。
跨类对照:Godot 3 升 4 的启示
再说个游戏行业自己的例子。Godot 4 的渲染器是从头重写的,3.x 的项目迁移是场硬仗。官方给出的方案是:一个转换工具、一份很长的迁移文档、一个兼容层。三件套都齐了,社区的迁移周期还是拉了一两年。
这件事的意义在于:引擎级的破坏性变更,代价是按“年”算的。Three.js 不会给你兼容层,因为它不是引擎,没这个义务。但你的团队如果把它当引擎用,那你就是那个必须自己造兼容层的人。早点认清这个角色,后面所有决策都会顺。
第四层:把升级做成一条可测的流水线
前面讲的全是判断,这一层讲落地。核心思路一句话:把 Three.js 升级当成一次版本发布来管,而不是当成一次依赖更新来管。依赖更新是“改个数字、跑起来、提交”;版本发布有基线、有测试、有灰度、有回滚。这两者的差别,就是“运气”和“工程”的差别。
第一件事:升级之前先留底片
这是被跳过最多、也最致命的一步。在升级前,固定机位、固定时间、固定参数,截 8 到 12 张图,全部提交进仓库当黄金基准。
关键细节:必须固定随机种子。如果你的地形是程序化生成的(本系列第 15 篇讲的那套噪声生成),如果粒子发射是随机的,如果植被散布是每帧重算的,那你的截图对比毫无意义,因为两次跑出来的画面本来就不同。这一条坑了很多人,他们做了一套对比工具然后发现天天报警,最后把工具关掉,等于白干。
第二件事:建一套“探针场景”
探针场景就是你项目的渲染冒烟测试。做法很简单:单独做一个极小的场景,把项目里所有渲染路径各过一遍,一个镜头一个关注点。它不需要好看,只需要可复现。
| 探针 | 覆盖的渲染路径 | 重点观察什么 |
|---|---|---|
| P01 材质球 | PBR 金属/非金属 + 环境贴图 | 高光形状是否收紧、环境反射强度是否偏亮 |
| P02 透明排序 | 玻璃、水面、半透明特效 | 前后遮挡对不对、有没有突然出现的穿插 |
| P03 阴影 | 方向光阴影 | 边缘是否发毛、有没有浮空(阴影与物体脱离)、有没有条纹自阴影 |
| P04 局部光衰减 | 点光源、聚光灯 | 光斑范围、暗部衰减曲线是否直觉 |
| P05 后处理链 | 泛光、色调映射、抗锯齿 | 泛光阈值是否还合适、暗部有没有断层 |
| P06 粒子与精灵 | 点精灵、公告板 | 尺寸随距离的衰减、混合模式、深度写入 |
| P07 骨骼动画 | 蒙皮、过渡混合 | 法线有没有跟着骨骼正确旋转、混合过渡是否抽搐 |
| P08 模型加载 | glTF + 压缩扩展 | 材质映射、贴图色彩空间、解压后是否有偏差 |
| P09 文字与面板 | 贴图字体、UI 面板 | 字边缘是否发糊、白色是不是还白 |
| P10 极端相机 | 超远裁面、超近裁面 | 深度精度、远处是否闪烁(Z 冲突) |
10 个探针,覆盖你项目 80% 的渲染路径。这里有个取舍:探针不是越多越好。超过 20 个,团队就没人愿意跑了,那还不如 8 个天天跑的。这套东西的价值在“被执行”,不在“被设计”。
第三件事:阈值要设得“能容忍”
视觉回归对比千万别要求零差异。不同显卡驱动的浮点计算结果本来就有微小出入,零阈值等于天天误报,三天后所有人都会学会无视那个红色警告——那时候这套系统就死了。
我的建议:全画面像素级差异超过 1% 报红,局部区块超过 3% 报黄,黄灯需要人眼确认。这两个数字不是玄学,是“能捕捉到色彩空间级别的变化,又不会因为驱动差异天天吵”的经验区间。
第四件事:灰度,Web 给你的免费礼物
Web 有一个单机游戏羡慕到流泪的能力:你可以按用户标识做分桶,让 5% 的真实玩家先跑新版本,其余人留在旧版本,随时能切回去。这在客户端游戏里要么做不到,要么得花大力气做补丁通道。
节奏我建议这样:内部全量 → 5% → 25% → 100%,每档观察 48 小时。观察什么?不是看报错日志。A 类变更会自己冒出来,用不着你盯。你要盯的是三样东西:玩家的截图和吐槽(尤其是“感觉颜色不对”这类模糊反馈)、帧率曲线的形状、以及美术在群里有没有开始骂人。这三样是 B 类变更唯一的探测器。
第五件事:回滚必须能在五分钟内完成
做不到这一条,前面四条都是表演。回滚不是“回滚代码”,是“把上一版构建产物重新指过去”。这意味着你得保留最近两到三个版本的完整构建产物,并且有一条验证过能用的切换路径。灰度最大的价值不是降低风险,是让团队敢于升级。一个知道随时能退回去的团队,升级频率会高得多,技术债也少得多。
版本治理配置表:把“感觉”变成能被讨论的数字
下面这张表是我自己在项目里用的,也是我跟主程吵架时能摆到桌面上的东西。它的作用不是精确,是让“升不升、多久升一次、升几个版本”这类问题从玄学变成可以商量的参数。
| 参数 | 含义 | 建议取值 | 为什么是这个数 |
|---|---|---|---|
| 升级窗口周期 | 两次主动升级之间隔多久 | 8 到 12 周 | 短于 6 周团队会烦,长于 16 周变更会积压成山 |
| 单次跨版本数 | 一次升级跨几个 r 版本 | 3 到 5 个 | 超过 8 个,变更说明读不完,出问题也定位不清 |
| 锁定粒度 | 依赖清单里的版本写法 | 精确版本号 | 0.x 上的 ^ 只锁补丁位,会给你“在跟随最新”的错觉 |
| 探针场景数量 | 冒烟场景做几个镜头 | 8 到 12 个 | 少于 5 个覆盖不全,多于 20 个没人跑 |
| 全画面差异阈值 | 整张截图差异多少报警 | 1% | 低于 0.3% 会被驱动差异天天误报 |
| 局部差异阈值 | 区块级差异多少报警 | 3% | 配合人眼确认,抓局部炸点 |
| 灰度档位 | 发布时的用户比例 | 5% / 25% / 100% | 每档至少 48 小时,能覆盖一个玩家活跃周期 |
| 灰度停留时长 | 每档观察多久 | 48 小时 | 短于 24 小时你看到的只是最活跃那批人 |
| 回滚保留版本数 | 保留几份历史构建 | 3 | 至少 2 个,1 个等于没有 |
| 弃用警告扫描 | 构建时是否扫运行时弃用日志 | 必开,且入库 | 全套体系里性价比最高的一条,见下 |
| 美术重调预留 | 每次升级给美术留的缓冲 | 0.5 到 1 人天 | 不预留,你的升级就是“带病上线” |
重点说“弃用警告扫描”这一条,因为它是整张表里最便宜也最容易被浪费的。Three.js 删一个东西之前,会先标记弃用、运行时打警告、保留一到两个版本,也就是一到两个月。这个窗口期就是官方免费发给你的预告片。
但现实是,绝大多数团队把它当噪音处理掉了:控制台一刷几十条警告,看得心烦,写个过滤规则全屏蔽。这就像家里烟雾报警器老响,你上楼把电池拔了。它响不是因为它坏了,是因为你家真的在冒烟。我的建议很粗暴:把弃用警告当技术债清单,看到一条就在任务系统里记一条,每个升级窗口清一遍。你能把这条执行下去,前面那些惊心动魄的迁移故事基本不会发生在你身上。
还有一条不在表里但同样重要:维护一张“我们的补丁账本”。每次为了绕过某个破坏性变更打的临时补丁,写清“为什么打、什么时候打的、对应哪个版本、什么时候可以撤”。不记这个,三年后你会在一块代码旁边看到一段没人敢删、也没人知道为什么在那里的判断逻辑。我见过最离谱的一块代码旁边的注释只有四个字:“历史原因”。那四个字的翻译是:我们也不知道,但删了会炸。
双路径:今晚别炸 vs 三年不塌
初级路径:你只想让今晚的构建别出事
记住五条,够用一年。
第一,版本钉死,写精确版本号,把锁文件提交进仓库。别迷信自动升级,尤其实验期。第二,升级之前先截 6 张图,存桌面都行,关键是让“变没变”有一个客观参照。第三,控制台里的弃用警告不要屏蔽,看到就当待办记下来,哪怕只是扔进一个文档里。第四,一次别升超过 5 个版本,跨 20 个版本你不是在升级,你是在重写。第五,升级安排在周一到周三,别在周五下午动渲染管线——这条听着像玩笑,但它是本文里被执行率最高的建议。
进阶路径:你希望三年后这个项目还能升得动
第一,建“版本雷达”。不是订一份发布日志然后不看,而是把日志当周报读,专门盯你项目里实际用到的四个模块:材质、后处理、加载器、动画。别的地方变了跟你没关系,这四个变了就是你的问题。
第二,把探针场景接进持续集成。每次提交自动跑截图对比,差异超标就不许合。这一条听起来重,做起来其实一个下午,因为它就是“拍图 + 比图 + 报警”三件事,没有算法难度,只有愿不愿意做的差别。
第三,灰度分桶 + 一键回滚,这两件事必须成对出现。只有灰度没有回滚,等于跳伞不带备伞;只有回滚没有灰度,等于买了备伞但从不跳。
第四,把“季度升级”写进路线图,单独占一行,不藏在“技术优化”条目下面。这是政治动作:它让升级变成一个被承认的工作量,而不是某个人的“顺便搞一下”。顺便搞一下的东西,永远排在下班后。
第五,给美术留半天。升级完让美术来看一眼,说一句“有没有不对”,比你跑一百次自动对比都管用。人的眼睛对“颜色不对”这件事极其敏感,而这个恰好是目前最难自动化的部分。
几个我踩过、或者眼睁睁看别人踩过的坑
坑一:“跟着最新版走最安全。”正好相反。最新版是全世界验证时间最短的版本,发布后的头两周是问题反馈最密集的时期。你的升级窗口如果刚好落在这两周里,你就是免费的小白鼠。慢一拍不丢人,那是给自己留缓冲。
坑二:只看更新日志里标了“破坏性”的那几行。大量的行为变更写在普通条目里:“默认值调整”“内部改用线性空间”“排序算法优化”。这些不带破坏性标签,但它们改的是你的画面。翻日志的正确姿势是:先扫破坏性条目(这些是必答题),再扫普通条目里所有带“默认”“现在”“改为”字样的句子(这些是陷阱题)。
坑三:以为类型检查能兜住。类型定义是某个人在某个时间点手写的,它跟运行时的实际行为之间存在时间差。类型通过不等于行为通过。所以你不能靠“编译过了”来验收一次升级,你必须看画面。
坑四:一次跨 20 个版本。你不是在升级,你是在做一次没有文档的考古。分成 4 次、每次 5 个版本,你能读到每一份变更说明,也知道是哪一次改坏了什么。分批的成本是时间,一次性的成本是“你不知道哪出了问题,只能全量回滚,然后什么也没学到”。
坑五:没有基线就升级。升级完发现画面变了,但你不知道变了多少、哪个镜头变了、是不是本来就这样。相当于体检不存底片,医生问你去年这个指标多少,你只能说“大概差不多”。
坑六:把弃用警告过滤掉。前面说过,这是你唯一的免费预告片。把预告片关掉,你就只剩下正片——而正片通常是一张白屏。
FAQ
Q1:我项目还停在很老的版本上,要不要一步到位升到最新?
不要。分四到六次走,每次跨 5 个版本左右。中间有两个点我建议你专门停一下:色彩空间那次改动、光照单位那次改动。这两刀是 r100 之后影响面最广的两次,单独升能让你定位清楚问题;一起来的话,你会同时面对画面变亮、变艳、变暗三件事,然后开始怀疑自己的显示器。
Q2:Three.js 以后会不会加上语义化版本?
我判断短期内不会。语义化版本是给“有商业承诺的库”准备的,它的迭代哲学就是快速演进、快速清理。你等不到那一天的,不如自己建一层——你的项目本来就是那层东西的天然位置。
Q3:我这依赖清单里写的是 ^,应该会自动升级吧?
在 0.x 上不会。脱字符在 0.x 上只允许补丁位变化,也就是 0.160.0 到 0.161.0 之前。很多人以为自己一直在跟踪最新,实际上一整年没动过。去查一眼你的锁文件,那个数字会告诉你真相。
Q4:团队里只有我一个人懂渲染,怎么说服老板批升级时间?
别说“升级”,说“季度画面保真检查”。老板听不懂着色器,但他听得懂“这个季度我们的画面会不会变、会不会被玩家发现不对”。把这件事包装成质量保障排期,别包装成技术债清理——技术债这三个字在任何会议室里都排最后。
Q5:项目已经上线且稳定,我能不能永远不升?
能,而且有时候这是对的选择。但你要睁着眼睛接受三个代价:新特性永远用不上(本系列第 01 篇讲的 WebGPU 那条线跟你无关了);浏览器兼容性会缓慢过期,没有哪个浏览器承诺永远兼容旧的图形调用;新人进不来,因为没人愿意学一套三年前的写法。钉死是一个合法选项,但它应该是“我知道我在放弃什么”的选择,不是“我没想过”的选择。
Q6:多大规模的项目才值得搞探针和视觉回归这套东西?
我的分界线是:这个项目还要维护超过六个月吗?是,就值得。这套东西前期大概花一个下午,收益是每次升级省下的一到两天查问题时间。小项目省下的绝对时间不多,但它省下的是“你敢不敢升”这件事——而不敢升,才是真正把项目拖死的东西。
最后留一个反直觉的观察给你。大部分 Three.js 项目的版本灾难,不是发生在升级的那一刻,而是发生在升级之后——升级本身很顺,跑起来没报错,团队松了一口气,庆祝了一下,然后一年半以后,美术突然说“我们这个海的颜色好像跟当初调的不一样了”,没人能说清是什么时候变的、是哪个版本变的、还是本来就这样。
所以版本治理真正要治的,从来不是“升级”这个动作。是“你以为没变”这件事。
你有没有过那种经历:某天打开自己半年前的项目,发现它看起来跟记忆里不太一样?如果有,那大概率不是你的记忆出了问题。你只是没留底片。