three.js r187 发布:关于WebGPU 渲染器和PMREM

three.js 在 2026 年 10 月 30 日发了 r187。这一版 PR 多到上百条,扫一遍挺费劲,但真正会影响你手上项目的其实就三件事:WebGPU 渲染器开始拆绘制管线、PMREM 换了实现、three/tsl 能 tree-shaking 了。

除此之外还有 9 条破坏性变更。其中三条会直接打断现有代码——灯光注册方式、TSL 结构体存储缓冲的访问方式、绑定渲染目标时 setViewport() 不再按像素比缩放。这三条后面单独说。

一句话概括:r187 是 WebGPU 渲染器从能跑起来往能组合着用走的一版,代价是 API 开始动了。

先交代材料。本文主要看的是官方 GitHub 的 r187 发布页,加上官方迁移指南里 186 → 187 那一节,PR 编号都对着发布页核过。

有两点得说清楚。发布页没给任何性能基准数字,文中出现的约 4 倍并行编译这类说法都来自 PR 描述,不是我们实测的。另外这版改动条目太多,本文只挑对生产项目有实际影响的部分,不做全量罗列,完整清单还得看发布页和迁移指南原文。

三条绘制管线:WebGPU 渲染器第一次把怎么画变成可选项

r187 里分量最重的一个 PR 是 #35191,一口气加了三个绘制管线类:

管线大致定位
StandardDrawingPipeline常规路径,逐对象提交绘制
MeshletDrawingPipeline以 meshlet(网格分片)为单位组织绘制,面向高密度几何
VisibilityBufferDrawingPipeline先写可见性缓冲、再延迟着色,面向大量小三角形

在 r187 之前,WebGPU 渲染器基本只有一条路:照搬 WebGL 那套逐对象绘制。而 meshlet 和 visibility buffer 恰好是 D3D12 / Vulkan 时代对付百万级三角面场景的标准手段。它们能成立的前提是拿得到 GPU 端的间接绘制和计算着色器,WebGL 时代做不到,WebGPU 才行。

对做城市级 3D 可视化的人来说,这条线的意思很直接:几何密度的天花板,正在从浏览器不支持变成你选哪条管线。

不过得提醒一句,三条管线在 r187 里还是新东西,成熟度和文档都在补。现在就把生产项目切过去,不太划算。

PMREM 换底:最容易被忽略的一条

PMREMGenerator(预过滤 mipmap 辐射环境贴图)这一版被重写了,从 CubeUV 图集改成立方体渲染目标(#34585)。

官方迁移指南里的原话是这样:

PMREMs are now based on cube render targets, see #34585. CubeUVReflectionMapping has been removed. The overall quality of PMREMs has been improved as well so materials will look slightly different with the new implementation.

翻译过来就是:CubeUVReflectionMapping 没了,PMREM 整体质量提升了,所以材质看上去会跟以前不太一样。

这条要单独拎出来说,是因为它不报错。你升级完,编译过了,控制台干净,但画面就是变了。要是项目里做过金属、清漆、玻璃这类吃环境反射的材质调校,升到 r187 之后必须重新看一遍渲染结果。尤其那些当初为了凑好看手动压过的粗糙度和环境光强度,现在大概率得回调。

材质与光照:EON BRDF 和虹彩参数拆分

改动PR影响
MeshPhysicalMaterial 新增 EON 粗糙漫反射 BRDF#34379粗糙表面的漫反射能量分布更接近物理,观感更实
iridescenceThicknessRange 拆成 iridescenceThicknessMinimum / iridescenceThicknessMaximum#35039旧字段弃用,薄膜干涉类材质(肥皂泡、油膜、珍珠)需要改代码
lambert / phong / toon 材质新增 emissiveNode#35059这三种基础材质也能走 TSL 节点驱动自发光
新增 LightMapper 漫反射光照烘焙器#34991静态场景可以预烘,省运行时算力

EON BRDF 值得单独说一句。它治的是粗糙表面边缘过暗、能量不守恒这类老毛病。建筑可视化、产品展示这种大面积漫反射材质的场景,观感提升比堆后期更实在。

性能与内存:几个能直接兑现的

  • three/tsl 可 tree-shaking(#34533)。以前只要 import 了 TSL,整个节点体系都会被拉进包里;现在没用到的不会打进去。对首屏体积敏感的项目,这条最实际。
  • 渲染器内部改用 WeakRef 和 FinalizationRegistry(#34368)。GPU 资源的释放不再完全靠手动 dispose(),漏掉的机会成本低了一些。但别理解成可以不 dispose。
  • LightProbeGrid 用 ArrayCamera 批量捕获探针(#34909)。PR 描述说烘焙速度提升约 4 倍。
  • compileAsync() 支持并行编译管线(#34816)。首帧卡顿有改善空间。

另外 BatchedMesh 修了一批问题,包括排序损坏、setGeometrySize() 之后的绘制范围、矩阵数据内存泄漏(#34828 / #34983 / #35272),还加了合并共享几何范围的连续绘制(#35259)。BatchedMesh 一直是 three.js 里最容易被误用、也最容易踩坑的模块,这轮修复的价值其实比新特性高。

九条破坏性变更:会打断代码的三条

迁移指南 186 → 187 那一节列了 9 条。下面这三条最容易直接报错,或者更麻烦的——静默出错:

变更旧写法新写法
灯光注册方式renderer.library.addLight( CustomLightNode, CustomLight )CustomLight.registerNode( CustomLightNode )
TSL 结构体存储缓冲storage.get( 'member' )storage.element( 0 ).get( 'member' )
绑定渲染目标时的视口缩放setViewport() / setScissor() 自动乘像素比不再自动乘,需自行处理

第二条特别阴。TSL 现在把结构体存储缓冲一律当数组看,哪怕只有一个元素。原来直接取成员的写法会失效,而且不一定报错,可能只是取到错的数据。这种 bug 排查起来能要命。

剩下 6 条是:TSL 数学函数隐式类型提升(#33695)、pixelationPass() 的 pixelSize 只接受 Number(#34543)、XR 相机矩阵改为取自第一个子相机(#34275)、ProxyNodeMaterial 更名 NodeMaterialInstance(#35269)、ViewportDepthNode.getProjectionDepth() 更名 projectionDepth()(#35230)、GTAOPass 移除组合深度/法线纹理支持(#34836)。

官方对升级节奏的建议是按每 10 个版本为一步递增,因为弃用警告只保留 10 个版本。从 r17x 直接跳到 r187,是最容易翻车的方式。

three.js r187 的关键改动分布:绘制管线、PMREM 重构、材质与性能优化、破坏性变更四个方向

几点判断

r187 真正放出的信号,是 WebGPU 渲染器开始有架构了。三条绘制管线不只是多了三个类,它意味着 three.js 承认了不同场景需要不同的绘制组织方式。这是引擎的思路,不是库的思路。长期做重场景交付的人该留意,只写个页面放个模型的人可以跳过。

最该做回归测试的是 PMREM。它属于典型的静默变更,不报错、不警告,画面就是不一样了。项目里如果有靠环境反射撑质感的部分,金属、玻璃、车漆、水面这些,升级前先截一组基准图,升级后逐帧比。

破坏性变更里最该小心的是 TSL 结构体缓冲那条,因为它不抛异常,只取错数据。项目里如果用了 storage( buffer, StructType ),升级时优先 grep 这一处。

也别被 PR 数量吓到。几百个 PR 里绝大多数是渲染器健壮性修复——深度纹理、阴影接缝、dispose 泄漏、缓存键。这些的价值不比新特性低,它们减少的是偶发黑屏切场景后花屏这种最难复现的问题。

至于要不要升:如果项目稳定在 r18x 又没有硬需求,不必为三条绘制管线动它。真要升,按官方建议分步走,PMREM 和 TSL 两处单独回归。新管线适合在独立分支上做技术验证,别和交付版本混在一起。


参考来源

  1. three.js r187 发布页:https://github.com/mrdoob/three.js/releases/tag/r187(2026-10-30)
  2. three.js 官方迁移指南(186 → 187):https://github.com/mrdoob/three.js/wiki/Migration-Guide#186--187
  3. three.js 仓库:https://github.com/mrdoob/three.js