fix-disposable-leak
诊断并修复 Disposable 内存泄漏。当用户提到内存泄漏 / memory leak / 未释放的 Disposable / Disposable leak(s) detected,或贴出带 trackDisposable / lifecycle.ts / computeLeakingDisposables 的泄漏堆栈时使用。
SKILL.md.claude/skills/fix-disposable-leak/SKILL.md
GitHub修复 Disposable 内存泄漏
本仓库用基于父子链的 DisposableTracker 检测泄漏。修复套路高度一致:找到泄漏对象的创建点 → 确认它没被挂到正确的父节点 → 用 _register / DisposableStore.add / React cleanup 把它挂上 → 加回归测试 → 验证。具体是哪个类、哪条业务路径泄漏,由你读代码当场判断。
检测机制(必须先理解,否则会误判)
源码:packages/platform/src/base/lifecycle.ts。
Disposable基类构造时会创建一个内部_store: DisposableStore,并把_store设为自身的子节点。所以一个泄漏的 Disposable 通常会报成两条:一条是new DisposableStore(在new Disposable里),一条是new Disposable本身,且两者idx连续。看到连续 idx 的这对,按同一个对象处理。- 判定“未泄漏”的唯一条件:该对象已被
dispose(),或它的根祖先被markAsSingleton标记。 - 父子链只由
DisposableStore.add(o)/this._register(o)建立(内部调setParentOfDisposable)。⚠️ 闭包里引用一个 disposable 不会建立父链 —— 仅仅() => foo.dispose()持有引用,foo的根仍是它自己,照样会被上报。要消除泄漏,必须真正_register/add。 - 渲染进程 tracker 在 DEV / E2E 安装:
apps/editor/src/renderer/main.tsx。所有根服务挂在单例workbenchStore = markAsSingleton(new DisposableStore())下,因此根服务即使不显式 dispose 也不会被报。 - 报告时机:
beforeunload里先reactRoot.unmount()再computeLeakingDisposables()(main.tsx 的snapshotLeaks)。意味着 ReactuseEffect的 cleanup 已经跑过——正常关窗路径下 React 订阅不会是元凶;元凶是没挂上父链、或挂错地方的对象。 - ⚠️ 但 reload 路径(Ctrl+Alt+R /
ReloadWindowAction)历史上有第二条检测点:它曾在弹"检测到 N 个泄漏"确认框前直接tracker.computeLeakingDisposables(),此时 React 还挂载着,于是把所有活跃的 useEffect 订阅(OutlineView/AiStatusBarItem 的onDidChangeXxx等)全误报成泄漏。报告头[renderer:reload](来自printLeaks的source)就是这条路径的指纹。判据:若同一批泄漏里 React useEffect 订阅扎堆、且报告来自 reload,先怀疑"检测时机错"(没先 unmount),而非订阅本身漏了——这类是假阳性。已修复为"reload 只markUnloadReason,检测交给 beforeunload"。 - 主进程也有 tracker(
apps/editor/src/main/index.ts,process.on('exit')时报告)。
排查流程
1. 解析泄漏报告
- 每条泄漏有
idx(创建序号)和创建堆栈。自底向上读堆栈:最靠近业务的那一帧(new XxxService/new XxxSession/someService.onDidChangeXxx)就是拥有者/创建点。 - 连续 idx + 同一构造点 = 同一对象的 Disposable/
_store对,合并看。 - idx 相差很大 = 不同事件、可能是互相独立的泄漏,分别处理,不要强行归因到一起。
- 核对路径与版本:堆栈里的绝对路径必须对得上当前工作目录。本仓库常有并行 checkout(如
universe-editorvsuniverse-editorN);路径 指向哪份就改哪份。- ⚠️ 行号陷阱:dev 下 vite 会把
.ts/.tsxtransform(剥离interface/type/JSDoc)后再发给浏览器,所以栈里lifecycle.ts:42这种行号通常比源文件(如 164)小一截,这是正常的,不代表旧代码。不要因为"行号对不上源文件"就断定报告陈旧——先看路径对不对。只有路径都指向另一份 checkout 时才是版本问题。
- ⚠️ 行号陷阱:dev 下 vite 会把
- 堆栈被截断(结尾像
(h)无法定位时,找用户要完整堆栈,不要瞎猜。
2. 定位创建点(用 Explore / Grep 并行扫)
- 用堆栈帧里的类名/事件名,Grep 出该构造函数或该事件的所有调用点。
- 横向对比:同一类对象往往有多条创建路径,其中一条正确
_register了、另一条漏了——漏的那条就是 bug。(本次案例:resumeSession()调了this._register(session),createSession()漏了。) - 确认拥有者本身是否挂在单例/被释放的父链上;如果拥有者没事,问题就在“拥有者→泄漏对象”这一环没建链。
3. 应用最小且一致的修复
按泄漏对象类型选手段:
- 某个
Disposable子类实例(service / view-model / session)→ 在其拥有者里this._register(theInstance),对齐同文件里已正确的兄弟路径。 - 事件订阅(
xxx.onDidChangeYyy(listener)返回的 disposable)→ 用this._register(...)包住;若在 React 里则useEffect返回() => d.dispose()。 toDisposable(fn)/ 定时器 / 监听器 → 同样_register/add。- ⚠️ 再次强调:别用闭包“假装”释放。必须真正进父链或显式
dispose()。 - 本仓库处于开发期、无需向后兼容;优先“最小、与既有范式一致”的改法。若发现累积型隐患(如 close 后仍被
_store持有直到服务销毁),可指出但默认不顺手大重构,除非用户要。
4. 加回归测试
测试位于 src/**/__tests__/*.test.ts(x)。两种写法:
- 直接断言级联释放(推荐,确定性强):构造拥有者 → 触发创建 →
owner.dispose()→ 断言子资源被释放(如底层连接disposed === true/ 状态变closed)。本次即给 fake 连接加disposed标记,断言svc.dispose()后conn.disposed === true。 - 用泄漏断言助手:
packages/platform/src/__tests__/_helpers/leakAssert.ts的withLeakCheck(fn)或useLeakCheck(),包住“创建→dispose”,自动断言无泄漏。注意它用全局 tracker,测试里 new 出来但没被拥有者接管的桩对象(history/storage 等)自身也会被算泄漏,必要时在用例内一并 dispose 或换用“级联释放”写法。 - 写完先验证测试能抓住 bug:移除修复行应当让新测试失败。
5. 验证
# 跑改动涉及的测试文件(按需替换路径)
pnpm --filter @universe-editor/editor exec vitest run --project renderer <test-file>
# 或平台包:pnpm --filter @universe-editor/platform test
pnpm --filter @universe-editor/editor typecheck
pnpm --filter @universe-editor/editor lint
# 提交前可跑全量:pnpm check
手动验证:pnpm --filter @universe-editor/editor dev 复现操作 → 关窗/Restart Editor → 看 dev console 不再打印对应 Disposable leak(s) detected。E2E 冒烟见 apps/editor/e2e/specs/smoke.disposableLeak.spec.ts。
关键参考路径
packages/platform/src/base/lifecycle.ts——DisposableTracker/computeLeakingDisposables/Disposable/DisposableStore/toDisposable/markAsSingleton/setDisposableTrackerapps/editor/src/renderer/main.tsx—— tracker 安装(DEV/E2E)、workbenchStore单例根、beforeunload报告apps/editor/src/main/index.ts—— 主进程 trackerpackages/platform/src/__tests__/_helpers/leakAssert.ts——withLeakCheck/useLeakCheckapps/editor/e2e/specs/smoke.disposableLeak.spec.ts—— E2E 泄漏冒烟
易踩坑速记
- 一个泄漏报两条(对象 + 其
_store),idx 连续,别当成两个 bug。 - 闭包引用 ≠ 建立父链,消不掉泄漏。
- React 订阅在正常关窗路径下不是元凶(报告前已 unmount);但 reload(
[renderer:reload])路径可能在 unmount 前检测,把活跃订阅全误报——这类是假阳性,修检测时机而非订阅。 - 根服务在单例下不被报——所以“没被报”不代表“被释放”。
- 只用路径判断改哪份 checkout;dev 栈的行号是 transform 后的(比源文件小),不能据此判定报告陈旧。
- 横向对比同类创建路径,漏
_register的那条就是 bug。 - 用 tracker 写回归测试时,
computeLeakingDisposables()无泄漏返回undefined(非null);contribution 回退new NullLogger()等桩对象自身会被算泄漏,给个返回markAsSingletonlogger 的 loggerService 桩绕开。 - 在飞请求的传输订阅(reload 时点):像
AiModelClientService.sendRequest这类"每次调用创建一组事件订阅、只在流结束(acceptEnd)时 dispose"的代码,reload 时若请求仍在飞,订阅未挂父链必被报。修法:把 combined 挂到 owner 的_store(根到单例即豁免),并让结束回调走this._store.delete(combined)(移除+dispose,避免 store 累积已 dispose 对象)——例如reassembler.bindSubscriptions(toDisposable(() => this._store.delete(combined)))。 - 延迟释放挂在宏任务上(e2e 泄漏门禁时点):
expectNoLeaks是同步快照,setTimeout(() => store.dispose(), 0)排的宏任务在快照时还没跑,整个 store 连同其成员被判泄漏——本地 dev 手动关窗看不到(人手速 >> 0ms),e2e 里约 50% 概率红。案例:preferencesActions.ts的pickTheme/SelectColorThemeAction,pick.onDidHide里用setTimeout(…, 0)推迟「未 accept 则回滚主题 + dispose」,被smoke.iconThemes.spec.ts抓成 5 条泄漏。修法:需要「让同回合的 accept 先赢」时用queueMicrotask而非setTimeout——微任务仍在当前回合内排空,既保住让位语义又不跨越快照点。判据:任何 disposable 的释放若排在宏任务/定时器上,都必须假设门禁会在它之前快照。 - 释放时机只绑在异步事件上(主进程退出时点):主进程 tracker 在
process.on('exit')报告,而子进程'exit'事件、流'close'、在飞fetch的finally(微任务,晚于 will-quit 的同步 dispose)在退出流程中来不及跑——只靠这类时机释放的 disposable 退出时必被报。修法:在同步可达的路径上补摘除(如 transport 的kill()里同步 dispose,toDisposable幂等,事件回调里的再 dispose 兜底)。案例:watcherUtilityTransport.ts;AI 远端源remote/httpJson.ts的fetchJson——同域已有正解providers/retry.ts的toAbortSignal(token, store)(取消回调里自己store.dispose(),与 cancel 同一 tick),新写的 fetch 路径漏用即复发,横向对比就能发现。
其它
- 后续用本 skill,发现新经验,需同步更新本文件
- 具体案例(信号 → 根因 → 修法/复现锚点)见 references/cases.md:早退丢弃孤儿 input、reload 同步卸载误报与真泄漏的区分、StrictMode 空跑 dispose 掉 useRef 持有的 Emitter