把内存泄漏做成可定位、可自动拦截的观测体系 | 杨元超的世界

读者是谁

这篇写给做 Three.js/WebGL、遇到「玩久了越来越卡」的开发者,以及负责端到端测试的同学;下面这张表按角色列出你能带走什么、从哪节开始读。

读者 带走什么 拿它做什么 从哪节开始读
做 Three.js/WebGL 的前端 owner + 对称释放的归属模型 给自己的临时对象加归属与批量释放 2
负责 E2E 测试的人 三轮循环的增量断言清单 把「两轮增量 = 0」写成持续集成(CI)里的断言 4
正在排查性能问题的人 按归属聚合的探针(临时诊断脚本) 直接抄去定位自己项目里未归属的对象 2 → 3

不做前端、不接触 WebGL 的读者不必读。

0 本文讲什么

这篇讲一次真实的内存泄漏排查:防御关卡一波波刷怪,连续打十几分钟后每秒帧数(FPS)下滑、内存只涨不跌;最终靠「给对象定归属 → 探针按归属聚合 → 三类泄漏逐个修 → 把每轮增量写成 E2E 断言」收口。先看概览,决定从哪节读起:

小节 讲什么 读它能得到什么
1 现象:场景树干净但显存涨 判断自己是不是同类泄漏
2 方法:owner + 按归属聚合的探针 一套可照抄的归属模型
3 三类泄漏点与各自修法 对号入座的修复思路
4 把计数写成 E2E 检查 一份增量断言清单
5 踩过的坑 采样失真等排查对照表
6 结论与下一步 今天就能做的一件事

1 现象:帧率在掉,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 回落。

2 方法:先定归属,再让探针按归属聚合

为什么需要归属:没有它时,清理逻辑是「谁创建谁记住」,创建点散在碰撞调试、寻路可视化、标签池、按距离切换的细节层级(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) 一栏数量最大。

2.1 需要准备什么

本地复现需要 Node 18 与 Playwright(浏览器自动化库);装依赖用 npm install -D playwright,采样脚本通过浏览器调试协议(CDP)读取页面里的探针变量(window.__MEM_PROBE__ 等)。

3 三类泄漏点

有了归属,问题拆成三种形态,修法完全不同。下面这张表是三类泄漏的对照:

泄漏类型 典型表现 修法 为什么这样修
挂错归属或没归属 碰撞调试 Box3Helper(Three.js 里画包围盒的辅助对象)、寻路 showFindedPath 每次新建几何材质 创建点收口到 owner,寻路线框改成每 owner 一条单例 Line2 归属唯一,释放才能整批;复用避免每次新建
早退跳过释放链 hardRemoveGirlMesh(拆分角色网格的函数)只清理两个 helper(辅助对象),后续挂的对象漏掉 每个 if (...) return 都检查是否跳过释放 函数不报错,只能靠逐分支审查发现
注册表只进不出 标签池上限 1000(单条约 35KB)、LOD(按距离切换的细节档位)调试框只在整队列销毁时释放 补对称注销,池上限从 1000 压到 256 上限是必须论证的数字,不是拍脑袋

4 从「能查」到「能拦」:把计数写成 E2E 检查

单次修复证明不了下一版不漏回来,所以把观测变成自动检查。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,才敢说「关内循环不泄漏」。

5 踩过的坑

下面按「是什么 → 为什么是坑 → 怎么解决 → 为什么能解决」排:

坑是什么 为什么是坑 如何解决 为什么能解决
页面被遮挡时采样 requestAnimationFrame 被节流到 1fps,数据全失真 采样期间保持页面可见/前台 采样频率恢复真实帧率,数字才可比
CDP session 用完不 detach 下次连接拿到脏状态 每次采样结束显式 detach 连接状态复位,下一次从干净会话开始
基线取首页 首页与关内对象池量级不同 基线取「刚进关卡」的点 比较的是同一状态下的增量
只看 scene.children.length 节点移除了但 GPU 资源没释放 同时读 renderer.info.memory 显存计数只随显式释放下降

6 结论与下一步

内存泄漏不是「找一个 bug」,而是「缺一套归属和基线」。三条可复用的判断标准:任何 scene.add 的临时对象必须同时有 owner 和对称释放;验证必须同时问 renderer.info.memory;一次修完不算完,要把「每轮增量为 0」写成可重复执行的断言。

你下一步能做什么:在你自己的场景里挑一个反复创建的对象类型,先加 owner 与对称释放,再用 renderer.info.memory 跑两轮对比;把「两轮增量 = 0」写成一条 E2E 断言,接入 CI。

这些内容来自哪里

这些内容来自一个真实项目里连续几周的内存排查:同一批对象连续跑了多轮采样,逐轮对比增量,才把三类泄漏点一个个分离出来。最后这些计数被写成自动检查,接入到日常验证流程。文中的增量和轮次都是当时实测的结果。

相关文章