这篇写给做 Three.js/WebGL、遇到「玩久了越来越卡」的开发者,以及负责端到端测试的同学;下面这张表按角色列出你能带走什么、从哪节开始读。
| 读者 | 带走什么 | 拿它做什么 | 从哪节开始读 |
|---|---|---|---|
| 做 Three.js/WebGL 的前端 | owner + 对称释放的归属模型 | 给自己的临时对象加归属与批量释放 | 2 |
| 负责 E2E 测试的人 | 三轮循环的增量断言清单 | 把「两轮增量 = 0」写成持续集成(CI)里的断言 | 4 |
| 正在排查性能问题的人 | 按归属聚合的探针(临时诊断脚本) | 直接抄去定位自己项目里未归属的对象 | 2 → 3 |
不做前端、不接触 WebGL 的读者不必读。
这篇讲一次真实的内存泄漏排查:防御关卡一波波刷怪,连续打十几分钟后每秒帧数(FPS)下滑、内存只涨不跌;最终靠「给对象定归属 → 探针按归属聚合 → 三类泄漏逐个修 → 把每轮增量写成 E2E 断言」收口。先看概览,决定从哪节读起:
| 小节 | 讲什么 | 读它能得到什么 |
|---|---|---|
| 1 | 现象:场景树干净但显存涨 | 判断自己是不是同类泄漏 |
| 2 | 方法:owner + 按归属聚合的探针 | 一套可照抄的归属模型 |
| 3 | 三类泄漏点与各自修法 | 对号入座的修复思路 |
| 4 | 把计数写成 E2E 检查 | 一份增量断言清单 |
| 5 | 踩过的坑 | 采样失真等排查对照表 |
| 6 | 结论与下一步 | 今天就能做的一件事 |
scene.children 却是干净的先补三个词:FPS(每秒帧数,越低越卡);显卡(GPU)资源指 geometry(几何体)、material(材质)、texture(贴图),要在代码里显式 dispose()(释放)才会还给显卡;垃圾回收(GC)只管 JS 对象,不管 GPU 资源。
防御关卡的结构很典型:一波波刷怪,「巨大娘」这类单位每次出现十几秒后被打死、销毁,下一轮再来。单轮看不出问题,连续打十几分钟,帧率明显下滑、内存只涨不跌。
最初去看 scene.children.length,每轮结束都回到原值——这个假象很能骗人:节点确实移除了,但 GPU 资源没跟着走。接入 renderer.info.memory 才看到真相:第 1 轮到第 2 轮,BufferGeometry 多 18 个、BufferAttribute(顶点属性缓冲)多 39 个、Material 多 27 个、Texture 多 9 个、Object3D 多 18 个,堆内存多约 4.7MB;而 Bone(骨骼)/SkinnedMesh(蒙皮网格)/Skeleton(骨架)/Group(分组)增量全是 0。骨骼网格没增,说明泄漏不是「角色模型没销毁」,而是每轮多出一批零碎对象。renderer.info.memory.textures 从 243 涨到 463,geometries 从 205 涨到 326,programs 从 29 涨到 43——这三个数只在显式释放时下调,不随 GC 回落。
为什么需要归属:没有它时,清理逻辑是「谁创建谁记住」,创建点散在碰撞调试、寻路可视化、标签池、按距离切换的细节层级(LOD)队列各处,每个模块只记得自己那一半,没人说得清「这个对象该由谁释放」。
怎么做:所有临时挂到场景上的对象都必须带 owner(归属标识,说明它属于哪次业务操作),释放时按 owner 整批回收。下面这段是登记与回收的最小实现(14 行):
const buckets = new Map<string, Set<Object3D>>()
export function registerSceneResource(ownerKey: string, object: Object3D) {
object.userData.__ownerKey = ownerKey
if (!buckets.has(ownerKey)) buckets.set(ownerKey, new Set())
buckets.get(ownerKey)!.add(object)
}
export function disposeSceneResources(state, ownerKey: string) {
for (const obj of buckets.get(ownerKey) ?? []) {
DisposeUtils.removeAndDispose(state, obj) // 移除 + geometry/material/texture 全链释放
}
buckets.delete(ownerKey)
}
好处:释放变成一次批量操作,不再按类型猜。只有归属还不够——得让「没归属的对象」自己暴露。于是加一个只读探针(probe,临时诊断脚本)listLineObjects,遍历场景按 type | owner 聚合,取前 10 名:
scene.traverse((obj) => {
if (!obj.isLine) return
const owner = obj.userData.__ownerKey ?? '(no-owner)'
const key = `${obj.type}|owner=${owner}`
counter[key] = (counter[key] ?? 0) + 1
})
按类型统计只能说「Line 对象太多」,按 owner 聚合会直接告诉你「这些属于谁、多少没挂 owner」。第一版跑出来,(no-owner) 一栏数量最大。
本地复现需要 Node 18 与 Playwright(浏览器自动化库);装依赖用 npm install -D playwright,采样脚本通过浏览器调试协议(CDP)读取页面里的探针变量(window.__MEM_PROBE__ 等)。
有了归属,问题拆成三种形态,修法完全不同。下面这张表是三类泄漏的对照:
| 泄漏类型 | 典型表现 | 修法 | 为什么这样修 |
|---|---|---|---|
| 挂错归属或没归属 | 碰撞调试 Box3Helper(Three.js 里画包围盒的辅助对象)、寻路 showFindedPath 每次新建几何材质 |
创建点收口到 owner,寻路线框改成每 owner 一条单例 Line2 |
归属唯一,释放才能整批;复用避免每次新建 |
| 早退跳过释放链 | hardRemoveGirlMesh(拆分角色网格的函数)只清理两个 helper(辅助对象),后续挂的对象漏掉 |
每个 if (...) return 都检查是否跳过释放 |
函数不报错,只能靠逐分支审查发现 |
| 注册表只进不出 | 标签池上限 1000(单条约 35KB)、LOD(按距离切换的细节档位)调试框只在整队列销毁时释放 | 补对称注销,池上限从 1000 压到 256 | 上限是必须论证的数字,不是拍脑袋 |
单次修复证明不了下一版不漏回来,所以把观测变成自动检查。E2E(端到端测试)指从页面入口驱动真实浏览器跑完整场景;这里的驱动工具是 Playwright(浏览器自动化库),采样通过 CDP(Chrome DevTools Protocol,浏览器调试协议)读取页面里的探针数据。
新增场景 mem-defense-rounds.json:同一关内连跑 3 轮「生成 → 击杀销毁」,每轮生成后、击杀后各采一点,共 7 个采样点。断言不看绝对内存(headless——无界面模式下抖动太大),只看同一采样模式跨轮次的增量:Three 对象类净增长为 0;角色注册表 mmdRegistered、characters、idToRecord 从 1 归 0;bufferPool(缓冲池)允许首轮从 9 长到 15,之后恒定;车体的三个缓存全程不变。跑通后,3 轮结束净增长回到 0,才敢说「关内循环不泄漏」。
下面按「是什么 → 为什么是坑 → 怎么解决 → 为什么能解决」排:
| 坑是什么 | 为什么是坑 | 如何解决 | 为什么能解决 |
|---|---|---|---|
| 页面被遮挡时采样 | requestAnimationFrame 被节流到 1fps,数据全失真 | 采样期间保持页面可见/前台 | 采样频率恢复真实帧率,数字才可比 |
| CDP session 用完不 detach | 下次连接拿到脏状态 | 每次采样结束显式 detach | 连接状态复位,下一次从干净会话开始 |
| 基线取首页 | 首页与关内对象池量级不同 | 基线取「刚进关卡」的点 | 比较的是同一状态下的增量 |
只看 scene.children.length |
节点移除了但 GPU 资源没释放 | 同时读 renderer.info.memory |
显存计数只随显式释放下降 |
内存泄漏不是「找一个 bug」,而是「缺一套归属和基线」。三条可复用的判断标准:任何 scene.add 的临时对象必须同时有 owner 和对称释放;验证必须同时问 renderer.info.memory;一次修完不算完,要把「每轮增量为 0」写成可重复执行的断言。
你下一步能做什么:在你自己的场景里挑一个反复创建的对象类型,先加 owner 与对称释放,再用 renderer.info.memory 跑两轮对比;把「两轮增量 = 0」写成一条 E2E 断言,接入 CI。
这些内容来自一个真实项目里连续几周的内存排查:同一批对象连续跑了多轮采样,逐轮对比增量,才把三类泄漏点一个个分离出来。最后这些计数被写成自动检查,接入到日常验证流程。文中的增量和轮次都是当时实测的结果。