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.
CubeUVReflectionMappinghas 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,是最容易翻车的方式。

几点判断
r187 真正放出的信号,是 WebGPU 渲染器开始有架构了。三条绘制管线不只是多了三个类,它意味着 three.js 承认了不同场景需要不同的绘制组织方式。这是引擎的思路,不是库的思路。长期做重场景交付的人该留意,只写个页面放个模型的人可以跳过。
最该做回归测试的是 PMREM。它属于典型的静默变更,不报错、不警告,画面就是不一样了。项目里如果有靠环境反射撑质感的部分,金属、玻璃、车漆、水面这些,升级前先截一组基准图,升级后逐帧比。
破坏性变更里最该小心的是 TSL 结构体缓冲那条,因为它不抛异常,只取错数据。项目里如果用了 storage( buffer, StructType ),升级时优先 grep 这一处。
也别被 PR 数量吓到。几百个 PR 里绝大多数是渲染器健壮性修复——深度纹理、阴影接缝、dispose 泄漏、缓存键。这些的价值不比新特性低,它们减少的是偶发黑屏切场景后花屏这种最难复现的问题。
至于要不要升:如果项目稳定在 r18x 又没有硬需求,不必为三条绘制管线动它。真要升,按官方建议分步走,PMREM 和 TSL 两处单独回归。新管线适合在独立分支上做技术验证,别和交付版本混在一起。
参考来源
- three.js r187 发布页:https://github.com/mrdoob/three.js/releases/tag/r187(2026-10-30)
- three.js 官方迁移指南(186 → 187):https://github.com/mrdoob/three.js/wiki/Migration-Guide#186--187
- three.js 仓库:https://github.com/mrdoob/three.js
