chrome-devtools-mcp 内存泄漏调试实战：堆快照采集、对比分析与保留链追踪完整工作流

本文基于 skills/memory-leak-debugging/SKILL.md 及其配套参考文档 common-leaks.md，系统讲解在 JavaScript 与 Node.js 应用中定位、诊断和修复内存泄漏的完整方法：从开启 --memoryDebugging 标志、用 MCP 工具采集基线/目标/回归三段式堆快照，到用 compare_heapsnapshots 做类级 diff、沿 dominator chain 追踪保留链，最后按五大常见泄漏模式落地修复。读完后你可以直接套用这套流程，让 coding agent 独立完成一次内存泄漏排查。

前置条件：--memoryDebugging 标志决定工具可用性

高级内存调试工具（compare_heapsnapshots、get_heapsnapshot_details 等）只有在服务器以 --memoryDebugging 标志启动时才可用。SKILL 文档要求：先检查这些工具是否可用；若不可用，再尝试读取 MCP 配置文件，确认 --memoryDebugging 是否已开启。

仓库中该标志的定义与默认值如下：

• 配置项定义于 mcp-options.ts：type: 'boolean'，default: false，别名为 --experimentalMemory（即 --memoryDebugging / --memory-debugging / --experimentalMemory 均可）；
• docs/configuration.md 将其归入服务器启动标志，默认值为 false；
• 从源码结构看，memory.ts 中除 take_heapsnapshot 外的所有内存工具都声明了 conditions: ['memoryDebugging']，即工具注册阶段就会按该标志门控——这也是为什么 agent 在未开启标志时会"看不到"这些工具，而不是调用时失败。

核心原则：四条不可妥协的操作纪律

SKILL 文档给出了四条核心原则，直接决定了调试过程的效率与安全性：

1. 优先使用 MCP 内存工具，绝不直接读取原始 .heapsnapshot 文件。堆快照文件极大（动辄数百 MB 的 JSON），直接读取会消耗海量 token 且无法解析。应使用 Chrome DevTools MCP 的堆快照工具来完成汇总（summarize）、对比（compare）和检查（inspect）。
2. 先隔离泄漏位置：判断泄漏发生在浏览器端（client-side）还是 Node.js 服务端（server-side），两者排查路径完全不同。
3. 盯住常见元凶：detached DOM 节点、未被清理的闭包、全局变量、未移除的事件监听器、无界增长的缓存。注意：detached DOM 节点有时是有意为之的缓存，置空引用前务必先与用户确认。
4. 调查结束后关闭已加载的快照：快照可能很大，每完成一项调查，应对每个已加载的快照调用 close_heapsnapshot，释放 MCP 服务器持有的内存。

内存工具全景：13 个工具及其参数

结合 memory.ts 与 tool-reference.md，Memory 分类下共有 13 个工具：

工具	所需标志	关键参数	用途
take_heapsnapshot	无（页面工具，需 pageId）	filePath	捕获页面堆快照并保存为 .heapsnapshot
get_heapsnapshot_summary	--memoryDebugging	filePath	加载快照并返回统计信息（含 native context 及大小、按 context 汇总的保留情况）
get_heapsnapshot_details	--memoryDebugging	filePath、filterName、objectId、pageIdx、pageSize	返回全部信息：统计、静态数据、聚合节点（支持分页与过滤）
get_heapsnapshot_class_nodes	--memoryDebugging	filePath、id、filterName、objectId、分页	列出某个类的全部实例及其节点 ID
get_heapsnapshot_retainers	--memoryDebugging	filePath、nodeId、分页	获取指定节点的反向保留者
get_heapsnapshot_retaining_paths	--memoryDebugging	filePath、nodeId、maxDepth、maxNodes、maxSiblings	获取保留路径，理解"为什么没被 GC"
get_heapsnapshot_dominators	--memoryDebugging	filePath、nodeId	获取 dominator chain，定位谁在维持目标存活
get_heapsnapshot_edges	--memoryDebugging	filePath、nodeId、sortBy、retainedSize、excludePrimitives	获取节点出边（引用），默认按 retainedSize 排序、默认排除基本类型
get_heapsnapshot_object_details	--memoryDebugging	filePath、nodeId	对象详情：size、type、distance、DOM detached 状态
compare_heapsnapshots	--memoryDebugging	baseFilePath、currentFilePath、classIndex	两份快照的对比；classIndex 省略时返回汇总 diff，指定时返回该类详细 diff
get_heapsnapshot_duplicate_strings	--memoryDebugging	filePath、分页	按值分组返回重复字符串
get_heapsnapshot_object_details 之外的 query_heapsnapshot_objects	--memoryDebugging	className、propertyName、nodeType、retainedSize、selfSize、isDetached、sortBy	按多重条件查询对象
close_heapsnapshot	--memoryDebugging	filePath	关闭已加载快照，释放内存

两点实现细节值得注意：

• 尺寸参数使用 byteSizeRangeSchema（见 bytes.ts），支持 "1MB-2MB"、"-1MB"、"1MB-" 等区间写法，单值视为下限；
• take_heapsnapshot 的 handler 会通过 context.ensureExtension(filePath, '.heapsnapshot') 自动补全扩展名，再调用 Puppeteer 的 captureHeapSnapshot 落盘（见 memory.ts 第 23-52 行），并受弹窗阻塞保护（blockedByDialog: true），避免对话框遮挡导致快照时机偏移。

工作流一：采集快照（三段式打点）

针对前端 Web 应用的内存泄漏，SKILL 文档给出的采集流程是：

1. 用页面级工具把页面驱动到目标状态：调用 click、navigate_page、fill 等工具（均指定 pageId），让应用执行触发泄漏的操作序列（如反复打开/关闭某个面板）。
2. 交互完成后把页面恢复到原始状态，观察内存是否释放——如果恢复后内存不降，说明泄漏基本坐实。
3. 重复同样的用户交互 10 次以放大泄漏，让 diff 信号淹没正常抖动。
4. 用 take_heapsnapshot（带 pageId）在三个关键时点把 .heapsnapshot 文件保存到磁盘：
   • baseline：交互前的基线状态；
   • target：完成 10 次交互后的状态；
   • final：恢复到原始状态后的状态。

这三个文件构成后续所有对比分析的输入。take_heapsnapshot 只需传 filePath（以及页面包络中的 pageId），响应会返回 Heap snapshot saved to <path> 确认信息。

工作流二：对比快照（先汇总，后钻取）

拿到 .heapsnapshot 文件后，按 SKILL 文档的顺序对比：

1. 先对每个快照调用 get_heapsnapshot_summary：一方面确认文件能被正常加载，另一方面比较高层总量（总对象数、native context 大小、按 context 的保留汇总）。get_heapsnapshot_summary 的 handler 会聚合四个数据源：getHeapSnapshotStats、getHeapSnapshotStaticData、getHeapSnapshotNativeContextSizes、getHeapSnapshotRetainedByContextSummary（见 memory.ts 第 54-90 行）。
2. 用 compare_heapsnapshots 对比 baseline 与 target：
   • 第一次不传 classIndex，得到按类聚合的 summary diff（每个类的 addedCount/removedCount/countDelta、addedSize/removedSize/sizeDelta，数据结构定义见 HeapSnapshotManager.ts 第 26-34 行）；
   • 只对可疑增长的类再传 classIndex（该类在 summary 列表中的 0-based 索引），拿到该类下逐个对象级别的详细 diff（含 addedIds、deletedIds 等，见 HeapSnapshotManager.ts 第 36-41 行）。
3. 先看 summary 输出，再钻取具体节点 ID——避免一开始就陷进海量对象细节里。

compare_heapsnapshots 的 handler 按 classIndex 是否存在走两条分支：有则调用 getHeapSnapshotDetailedClassDiff，无则调用 getHeapSnapshotClassDiffs（见 memory.ts 第 367-411 行）。

工作流三：检查保留者与 dominator chain

当某个类或对象类型出现异常增长，改代码之前先搞清楚"它为什么还被可达"。SKILL 文档推荐的检查顺序：

1. get_heapsnapshot_class_nodes：列出可疑类的实例，拿到代表性的节点 ID；
2. get_heapsnapshot_retainers、get_heapsnapshot_retaining_paths、get_heapsnapshot_dominators、get_heapsnapshot_edges：四个工具分别回答不同问题——
   • retainers：谁直接持有它（反向引用）；
   • retaining paths：从可达根到它的路径（可限 maxDepth/maxNodes/maxSiblings 控制规模）；
   • dominators：dominator chain，即"删掉谁，这个对象就真的会消失"；
   • edges：它自己向外引用了什么（默认 sortBy: 'retainedSize'、excludePrimitives: true，见 memory.ts 第 289-336 行）；
3. get_heapsnapshot_object_details（传具体 nodeId）：获取对象元数据——大小、类型、距离、DOM detached 状态；
4. 如果 diff 中字符串增长占主导，改用 get_heapsnapshot_duplicate_strings：按值分组列出重复字符串，常指向被缓存的日志、序列化结果或未去重的数据。

保留路径一旦指向应用代码，就进入下一节的泄漏模式匹配。

工作流四：分类过滤器直查泄漏类别

不必绕道外部工具，MCP 内置了按"泄漏成因"分类的过滤器。在 get_heapsnapshot_details 或 get_heapsnapshot_class_nodes 上传 filterName：

过滤器	定位目标
objectsRetainedByDetachedDomNodes	被 detached DOM 元素拖在内存里的对象
objectsRetainedByEventHandlers	被未移除的事件监听器保活的对象
objectsRetainedByContexts	被困在闭包/执行上下文中的对象
objectsRetainedByConsole	被 console 日志持有的对象

源码中 HEAP_SNAPSHOT_FILTERS 实际定义了 7 个取值（见 memory.ts 第 13-21 行），除上述四个外还有 sharedNativeContext、noNativeContext、attributedToSpecificNativeContext 三个 native context 维度过滤器。注意：使用 attributedToSpecificNativeContext 时必须同时传 objectId（目标 native context 的节点 ID），否则 HeapSnapshotManager 会直接抛出 objectId is required... 错误（见 HeapSnapshotManager.ts 第 96-116 行）——该过滤器内部会把 objectId 解析为节点下标，映射成 nativeContext_<index> 形式的底层过滤名。

常见泄漏模式与修复清单

SKILL 配套文档 common-leaks.md 给出了在保留路径、dominator chain 或类 diff 中应匹配的 5 类模式：

1. 未清理的事件监听器：挂在 window、document 或长生命周期对象上的监听器，会通过回调闭包阻止被引用对象被 GC。 修复：组件卸载或监听器不再需要时，务必调用 removeEventListener。
2. Detached DOM 节点：节点已从文档树移除，但仍被 JS 变量引用。detached 是好的泄漏信号，但不总是 bug——有些站点会刻意缓存 detached 导航树。 修复：先把这些节点呈报给用户；置空引用或改代码之前先征询用户，确认是泄漏后，再在移除节点时把持有 DOM 引用的变量置 null 或收窄其作用域。
3. 意外的全局变量：非严格模式下未用 var/let/const 声明的变量、或显式挂到 window 上的属性，会永久驻留内存。 修复：启用严格模式、规范声明变量、避免全局状态。
4. 闭包：闭包会意外持有外层作用域中的大对象引用。 修复：不再需要时置空大对象，或重构闭包使其不捕获非必要变量。
5. 无界缓存/数组：用对象、Array、Map 做缓存但不设上限，随使用量单调增长。 修复：加缓存上限、改用 LRU 缓存，或改用 WeakMap/WeakSet 承载与对象生命周期绑定的数据。

底层实现证据：快照为什么能"轻量"地分析

从源码结构看，所有读类工具都经由 McpContext 持有的单例 HeapSnapshotManager（见 McpContext.ts）：

• 文件校验与缓存：getSnapshot 先校验扩展名必须是 .heapsnapshot 或 .heaptimeline，再以绝对路径为 key 缓存已加载的 HeapSnapshotProxy（见 HeapSnapshotManager.ts 第 51-94 行）。同一文件被多个工具反复查询时不会重复解析——这正是"文件很大但工具响应快"的原因。
• 独立 Worker 解析：每个快照在后台 worker 中加载（HeapSnapshotProxy + HeapSnapshotWorkerProxy，类型来自 third_party 引入的 DevTools 前端 HeapSnapshotModel），解析与聚合计算不阻塞 MCP 服务器主进程。
• 类 ID 映射：manager 为每个快照维护 idToClassKey / classKeyToId，把 get_heapsnapshot_details 输出的类 ID 翻译成内部类键，供 get_heapsnapshot_class_nodes 按 ID 查实例。
• 生命周期：McpContext 销毁时会调用 #heapSnapshotManager.dispose() 统一释放全部已加载快照与 worker；单个快照则通过 close_heapsnapshot 提前释放——对应 SKILL 文档"调查结束后逐个 close"的原则。close_heapsnapshot 对未加载的文件会抛出明确错误（was not loaded），便于发现重复关闭。

收尾检查清单

一次完整的泄漏排查应按此闭环结束：

1. baseline / target / final 三份快照均已落盘；
2. get_heapsnapshot_summary 确认三份文件可加载，final 与 baseline 的差距量化了泄漏量；
3. compare_heapsnapshots 锁定可疑类，必要时用 classIndex 拿到对象级 diff；
4. retainers / retaining paths / dominators 指向具体应用代码，并对号入座 common-leaks.md 的五大模式；
5. 确认 detached DOM 缓存等"疑似泄漏"是否为用户有意为之（先问再改）；
6. 对每个已加载快照调用 close_heapsnapshot，释放 MCP 服务器内存。

相关资源

• skills/memory-leak-debugging/SKILL.md：本技能的主文档（前置条件、核心原则、四个工作流）；
• skills/memory-leak-debugging/references/common-leaks.md：五大常见泄漏模式与修复；
• src/tools/memory.ts：13 个内存工具的完整 schema 与 handler 实现；
• src/processors/HeapSnapshotManager.ts：快照加载、缓存、过滤与 diff 的底层管理器；
• docs/configuration.md：--memoryDebugging 启动标志说明；
• docs/tool-reference.md：Memory 分类工具逐参数参考；
• tests/processors/HeapSnapshotManager.test.ts、tests/tools/memory.test.ts：管理器与工具的测试用例，可用于理解各方法的边界行为。