memlab 命令行完全指南:从内存泄漏检测到堆快照分析的 CLI 命令全解
memlab 命令行完全指南:从内存泄漏检测到堆快照分析的 CLI 命令全解
MemLab 是面向前端 JavaScript 应用的内存泄漏检测与堆快照分析框架。它提供的 CLI 工具以 memlab 命令为核心入口,覆盖"驱动浏览器执行 E2E 交互 → 采集堆快照 → 分析泄漏 → 输出保留路径(retainer trace)"的完整链路。本篇指南以仓库中的 CLI-commands.md 为骨架,结合 packages/cli 下的源码实现,逐一详解 memlab run、find-leaks、diff-leaks、trace、analyze、snapshot、measure 等全部命令的用法、全部可选参数及底层运行机制。读完本文,你将能够独立编写测试场景(scenario)文件、通过命令行定位 JavaScript 内存泄漏、对堆快照做匿名化与深度分析,并将 MemLab 接入自己的 E2E 测试流水线。
安装 memlab 命令行工具
MemLab CLI 通过 npm 全局安装:
npm install -g memlab
安装完成后,直接在终端输入 memlab 即可看到命令分类总览。仓库中 CLI 的入口实现位于 packages/cli/src/Dispatcher.ts:当不带任何命令调用 memlab 时,CommandDispatcher.dispatch 会检测到参数缺失,自动调用 helper 命令打印全部命令及选项(见 Dispatcher.ts)。
COMMON 命令:日常泄漏检测与快照分析主力
CommandCategory.COMMON(见 BaseCommand.ts)收纳了最常用的 8 组命令。这些命令由 CommandLoader.ts 在启动时扫描 packages/cli/src/commands 目录自动注册——凡是文件名以 Command.js 结尾且继承自 BaseCommand 的类都会成为一条 CLI 命令。
memlab run:在真实浏览器中查找内存泄漏
memlab run 是端到端(E2E)泄漏检测的旗舰命令:它会启动 Chromium 浏览器,按测试场景文件驱动页面交互,在交互前、中、后分别采集堆快照,然后自动完成泄漏分析。
memlab run --scenario <TEST_SCENARIO_FILE>
场景文件是导出 url、action、back 等回调的 JS 模块,示例可参考仓库中的 packages/e2e/static/example/scenarios/detached-dom.js。
示例
memlab run --scenario /tmp/test-scenario.js
memlab run --scenario /tmp/test-scenario.js --work-dir /tmp/test-1/
选项
| 选项 | 说明 |
|---|---|
--work-dir |
设置本次运行的 working directory,所有产物(快照、报告)都会写入该目录 |
--headful |
以有头模式启动浏览器(默认 headless) |
--display-leak-outlines |
在有头浏览器中高亮泄漏组件轮廓,需与 --headful 搭配使用 |
--full |
对 E2E 交互中的每一步都采集堆快照 |
--skip-screenshot |
跳过截图 |
--skip-gc |
跳过浏览器内的垃圾回收(默认会主动触发 GC 以获得干净的堆) |
--skip-scroll |
跳过对目标页面的滚动 |
--skip-extra-ops |
跳过在目标页和最终页上的额外交互(如滚动、等待) |
--local-puppeteer |
通过本地 puppeteer 对远程浏览器实例进行调试 |
--scenario |
指定测试场景文件路径 |
--chromium-binary |
指定 E2E 运行使用的 Chromium 可执行文件 |
--protocol-timeout |
设置 Chromium 连接的协议超时(毫秒)。默认 180000;当堆快照过大(如超过 1GB)且页面报 ProtocolError: HeapProfiler.takeHeapSnapshot timed out 时,应通过此参数增大超时 |
--device |
设置模拟的设备类型 |
--user-agent |
设置 E2E 交互中的浏览器 UserAgent,否则使用 Chromium 默认值 |
--disable-xvfb |
禁用 Xvfb(X virtual framebuffer)模拟有头渲染 |
--disable-web-security |
关闭 Chromium 的 web security 以允许跨域请求(默认开启) |
--rewrite-js |
启用浏览器内 JavaScript 插桩 |
--log-script |
启用浏览器内 JavaScript 的拦截与日志 |
--worker |
设置需要选择并分析的目标 worker 标题 |
--leak-filter |
指定泄漏过滤器定义 JS 文件 |
--trace-object-size-above |
保留尺寸(字节)超过该阈值的对象将被视为泄漏 |
--ignore-leak-cluster-size-below |
忽略聚合保留尺寸小于该阈值(字节)的泄漏簇 |
--trace-all-objects |
忽略泄漏过滤器,为所有分配对象导出保留路径。可选模式:--trace-all-objects=selected-js-objects、--trace-all-objects=default |
--save-trace-as-unclassified-cluster |
将每条保留路径导出为一个 unclassified 簇 |
--ml-clustering |
使用机器学习算法对泄漏轨迹聚类(默认按启发式聚类) |
--ml-linkage-max-dist |
设置聚类 linkage 最大距离,取值区间为 [0, 1](含端点) |
--ml-clustering-max-df |
按百分比设置最大文档频率,用于限制出现过于频繁的 term |
--clean-up-snapshot |
运行结束后清理堆快照 |
--help / -h |
打印帮助文本 |
--verbose / -v |
显示更多细节 |
--sc |
开启 continuous test 模式 |
--debug |
开启手动调试 |
--silent / -s |
静默所有终端输出 |
源码视角:run 命令的执行链
memlab run 的实现位于 MemLabRunCommand.ts。它声明了三个前置命令(prerequisites):InitDirectoryCommand(初始化目录)、TakeSnapshotCommand(驱动浏览器交互并采集快照)、CheckLeakCommand(分析泄漏)。这正是 Dispatcher.ts 的调度逻辑:执行当前命令前会先递归执行其 getPrerequisites(),保证目录、快照、分析按序完成,且已执行过的命令不会重复执行。run 方法最后把 leaks.txt 从输出目录复制到当前数据目录,供后续 find-leaks 等命令复用。
--trace-object-size-above 与 --trace-all-objects 的解析见 OversizeThresholdOption.ts 与 TraceAllObjectsOption.ts:前者会同时设置 oversizeObjectAsLeak = true 与 oversizeThreshold;后者则进一步把阈值归零并依据 selected-js-objects / default 设置追踪模式。
memlab anonymize:匿名化堆快照以便共享
线上堆快照往往包含用户数据(姓名、消息、token 等),直接共享存在泄露风险。memlab anonymize 从堆快照中移除这些用户数据,生成一份可安全对外分享的副本。
memlab anonymize --snapshot <HEAP_SNAPSHOT_FILE> --output <OUTPUT_FILE>
示例
memlab anonymize --snapshot <HEAP_SNAPSHOT_FILE> --output <OUTPUT_FILE> --anonymize-salt <SALT>
memlab anonymize --snapshot <HEAP_SNAPSHOT_FILE> --audit-only
选项
| 选项 | 说明 |
|---|---|
--snapshot |
设置待分析的堆快照文件路径 |
--snapshot-dir |
设置包含全部待分析堆快照的目录路径 |
--output |
设置匿名化堆快照的输出文件路径 |
--anonymize-mode |
设置脱敏文本的生成方式:stable(默认)保持不同值的差异性,使重复性分析依然准确;uniform 将每个字符替换为 ? |
--anonymize-salt |
为替换文本设置盐值。不设盐时每次采集的映射一致——这便于同一组快照相互比较,但也让任何持有候选值的人可以反向确认。同一组文件务必使用同一个盐 |
--audit-only |
只报告会被脱敏和保持明文的内容,不写文件。可对别人已匿名化的快照再次运行,以检查是否有遗漏 |
--help / -h |
打印帮助文本 |
--verbose / -v |
显示更多细节 |
--sc |
开启 continuous test 模式 |
--debug |
开启手动调试 |
--silent / -s |
静默所有终端输出 |
源码视角:安全兜底逻辑
AnonymizeSnapshotCommand.ts 对输出做了多重防护:
--audit-only与--output同时给出时,会明确警告--output被忽略(因为审计模式不写文件);- 既没有
--output也没有--audit-only时直接终止运行,拒绝猜测输出路径; - 输出路径与输入快照解析为同一文件时(包括相对路径、symlink 等写法)会直接报错终止,防止原地覆盖摧毁唯一一份未脱敏原始快照。
命令内部调用 anonymizeHeapSnapshotFile / auditHeapSnapshotFile(来自 @memlab/core,核心实现见 HeapAnonymizer.ts),并会在结束时输出报告:被脱敏的字符串值数量、按内容规则(数字串、哈希、token 等)额外脱敏的数量、为保留可读结构标签而拆分的条目数,以及仍处于明文中、需要在分享前人工复查的标签形状族。
memlab find-leaks:对堆快照文件做泄漏分析
memlab find-leaks 不依赖浏览器,直接对已采集的堆快照文件做泄漏检测。它有三种指定输入的方式:
--baseline、--target、--final分别指定三份堆快照文件;--snapshot-dir指定包含三份快照的目录(MemLab 按文件名的字母序自动分配 baseline、target、final);--work-dir指定memlab run或memlab snapshot的输出工作目录。
三种方式互斥,一次只能使用其中一种。
你也可以在 Chrome DevTools 中手动采集堆快照保存到磁盘,然后用方式 1 或 2 交给该命令处理。
# 分析 memlab run 默认工作目录(未设置 --work-dir 时)中的内存泄漏
memlab find-leaks
示例
# 分别指定 baseline、target、final 堆快照文件路径
memlab find-leaks --baseline /tmp/baseline.heapsnapshot --target /tmp/target.heapsnapshot --final /tmp/final.heapsnapshot
# 指定包含三份堆快照文件的目录
memlab find-leaks --snapshot-dir /dir/containing/heapsnapshot/files/
# 指定 memlab run 或 memlab snapshot 的输出工作目录
memlab find-leaks --work-dir /memlab/working/dir/generated/by/memlab/
选项
| 选项 | 说明 |
|---|---|
--baseline |
设置 baseline 堆快照文件路径 |
--target |
设置 target 堆快照文件路径 |
--final |
设置 final 堆快照文件路径 |
--snapshot-dir |
设置包含全部堆快照的目录路径 |
--engine |
设置 JavaScript 引擎(默认 V8) |
--leak-filter |
指定泄漏过滤器定义 JS 文件 |
--trace-object-size-above |
保留尺寸(字节)超过该阈值的对象视为泄漏 |
--ignore-leak-cluster-size-below |
忽略聚合保留尺寸小于该阈值(字节)的泄漏簇 |
--trace-all-objects |
忽略泄漏过滤器为所有对象导出保留路径,可选模式同上 |
--save-trace-as-unclassified-cluster |
将每条保留路径导出为 unclassified 簇 |
--ml-clustering |
用机器学习对泄漏轨迹聚类(默认启发式聚类) |
--ml-linkage-max-dist |
linkage 最大距离,区间 [0, 1](含端点) |
--ml-clustering-max-df |
基于百分比的最大文档频率 |
--clean-up-snapshot |
运行结束后清理堆快照 |
--work-dir |
设置当前运行的 working directory |
--heap-parser-dict-fast-store-size |
堆快照解析器中 fast store 切换为较慢 store 的尺寸阈值,默认 5,000,000。若遇到 FATAL ERROR: invalid table size Allocation failed - JavaScript heap out of memory,尝试调低该阈值 |
--help / -h |
打印帮助文本 |
--verbose / -v |
显示更多细节 |
--sc |
开启 continuous test 模式 |
--debug |
开启手动调试 |
--silent / -s |
静默所有终端输出 |
源码视角:find-leaks 的输入与聚类默认值
CheckLeakCommand.ts 实现了 find-leaks:run() 中会先根据 --work-dir 初始化目录与 run meta,然后关闭 weak map 边追踪(config.chaseWeakMapEdge = false),调用 analysis.checkLeak() 完成分析,最后按 --clean-up-snapshot 决定是否删除快照文件。它的三个输入方式的文档说明正是从源码 getDocumentation()(见 CheckLeakCommand.ts)直接生成的,保证了 CLI 帮助文本与本文档一致。
memlab diff-leaks:对比对照组与实验组的泄漏差异
在 A/B 类实验中,常需要回答"这次改动引入了哪些新泄漏"。memlab diff-leaks 通过对比 control(对照组)与 treatment(实验组)的堆快照找出新增泄漏。
memlab diff-leaks
选项
| 选项 | 说明 |
|---|---|
--control-snapshot |
设置对照组运行的单份(target)快照 |
--control-work-dir |
设置对照组运行的 working directory |
--treatment-snapshot |
设置实验组运行的单份(target)快照 |
--treatment-work-dir |
设置实验组运行的 working directory |
--engine |
设置 JavaScript 引擎(默认 V8) |
--leak-filter |
指定泄漏过滤器定义 JS 文件 |
--trace-object-size-above |
保留尺寸超过该阈值的对象视为泄漏 |
--ignore-leak-cluster-size-below |
忽略聚合保留尺寸小于该阈值的泄漏簇 |
--trace-all-objects |
忽略泄漏过滤器为所有对象导出保留路径 |
--save-trace-as-unclassified-cluster |
将每条保留路径导出为 unclassified 簇 |
--ml-clustering |
用机器学习对泄漏轨迹聚类 |
--ml-linkage-max-dist |
linkage 最大距离,区间 [0, 1](含端点) |
--ml-clustering-max-df |
基于百分比的最大文档频率 |
--max-cluster-sample-size |
指定输入到泄漏轨迹聚类算法的最大轨迹数。样本越大信息越完整,但可能冒内存溢出(OOM)崩溃的风险 |
--trace-contains |
设置节点名或边名,过滤包含该名称的泄漏轨迹 |
--heap-parser-dict-fast-store-size |
快照解析器 fast store 切换阈值,默认 5,000,000,OOM 时报错可调低 |
--work-dir |
设置当前运行的 working directory |
--help / -h |
打印帮助文本 |
--verbose / -v |
显示更多细节 |
--sc |
开启 continuous test 模式 |
--debug |
开启手动调试 |
--silent / -s |
静默所有终端输出 |
源码视角:缺少参数时的行为
实现见 DiffLeakCommand.ts。若未指定任何 control/treatment 的 work-dir 或 snapshot,命令会抛出明确的终止提示,引导用户补全 --control-snapshot 与 --treatment-snapshot,或改用 --control-work-dir 与 --treatment-work-dir。分析最终通过 analysis.diffLeakByWorkDir({controlWorkDirs, treatmentWorkDirs}) 完成,输出目录以 treatment 的 work-dir 为准。
memlab trace:查询单个堆节点的保留路径
memlab trace 报告指定堆节点的保留路径(retainer trace),即"谁通过什么引用链把这个对象留在堆上"——这是定位泄漏根因的核心手段。需配合 --node-id 使用。
memlab trace --node-id=<HEAP_OBJECT_ID>
示例
memlab trace --node-id=@3123123
memlab trace --node-id=128127
选项
| 选项 | 说明 |
|---|---|
--snapshot |
设置待分析的堆快照文件路径 |
--snapshot-dir |
设置包含全部堆快照的目录路径 |
--engine |
设置 JavaScript 引擎(默认 V8) |
--node-id |
设置堆节点 ID(必填) |
--heap-parser-dict-fast-store-size |
快照解析器 fast store 切换阈值,默认 5,000,000 |
--help / -h |
打印帮助文本 |
--verbose / -v |
显示更多细节 |
--sc |
开启 continuous test 模式 |
--debug |
开启手动调试 |
--silent / -s |
静默所有终端输出 |
实现见 GetRetainerTraceCommand.ts:它把 --node-id 标记为 required 选项,运行前清空报告输出目录,再通过 analysis.focus({file}) 定位节点并输出保留路径。
memlab analyze:在堆快照上运行各类分析插件
memlab analyze 是通用分析入口,语法为:
memlab analyze <PLUGIN_NAME> [PLUGIN_OPTIONS]
它通过 HeapAnalysisCommand.ts 实现:运行时用 heapAnalysisLoader.loadAllAnalysis() 加载全部内置分析插件,并把每个插件包装成 HeapAnalysisSubCommandWrapper 子命令(见 HeapAnalysisSubCommandWrapper.ts);若插件名缺失或非法,会打印帮助后终止。
选项
| 选项 | 说明 |
|---|---|
--analysis-plugin |
指定外部堆分析插件文件(必须是后缀为 Analysis.js 的纯 JS 文件) |
--heap-parser-dict-fast-store-size |
快照解析器 fast store 切换阈值,默认 5,000,000 |
--work-dir |
设置当前运行的 working directory |
--help / -h |
打印帮助文本 |
--verbose / -v |
显示更多细节 |
--sc |
开启 continuous test 模式 |
--debug |
开启手动调试 |
--silent / -s |
静默所有终端输出 |
内置分析子命令
以下 14 个子命令对应 packages/heap-analysis/src/plugins/ 下的分析插件(各插件的 getCommandName() 定义了子命令名):
memlab analyze unbound-collection:检测无界集合增长(如 Map 条目数不断增长)
memlab analyze unbound-collection
选项:--snapshot-dir(设置包含全部堆快照的目录),以及通用选项 --help/-h、--verbose/-v、--sc、--debug、--silent/-s。实现:CollectionUnboundGrowthAnalysis.ts
memlab analyze collections-with-stale:分析持有过期对象的集合
memlab analyze collections-with-stale
选项:--snapshot(堆快照文件路径)、--output(输出格式,可选 text/json,默认 text)及通用选项。实现:CollectionsHoldingStaleAnalysis.ts
memlab analyze detached-DOM:获取已脱离文档的 DOM 元素(detached DOM elements)
memlab analyze detached-DOM
选项:--snapshot、--output(text/json,默认 text)及通用选项。实现:DetachedDOMElementAnalysis.ts
memlab analyze global-variable:获取堆中的全局变量
memlab analyze global-variable
选项:--snapshot、--output(text/json,默认 text)及通用选项。实现:GlobalVariableAnalysis.ts
memlab analyze object:获取对象内部的属性
memlab analyze object
选项:--snapshot、--node-id(堆节点 ID)、--output(text/json,默认 text)及通用选项。实现:ObjectContentAnalysis.ts
memlab analyze object-fanout:获取堆中出边引用最多的对象
memlab analyze object-fanout
选项:--snapshot、--output(text/json,默认 text)及通用选项。实现:ObjectFanoutAnalysis.ts
memlab analyze object-shallow:按 key/value 获取对象,但不递归进入子对象
memlab analyze object-shallow
选项:--snapshot 及通用选项。实现:ObjectShallowAnalysis.ts
memlab analyze shape:列出占用内存最多的对象形状(shape)
memlab analyze shape
选项:--snapshot 及通用选项。实现:ObjectShapeAnalysis.ts
memlab analyze object-size:获取堆中最大的对象
memlab analyze object-size
选项:--snapshot、--output(text/json,默认 text)及通用选项。实现:ObjectSizeAnalysis.ts
memlab analyze unbound-object:检测单个对象保留尺寸的无界增长
memlab analyze unbound-object
选项:--snapshot-dir 及通用选项。实现:ObjectUnboundGrowthAnalysis.ts
memlab analyze react-hooks:展示最耗内存的 React 组件及其 hooks 的内存细分。在 React Dev 模式下未压缩的堆快照上效果最佳,也支持生产模式下压缩的堆快照
memlab analyze react-hooks
选项:--snapshot 及通用选项。实现:ReactComponentHookAnalysis.ts
memlab analyze unbound-shape:检测无界增长的形状(一类聚合保留尺寸持续增长的对象)
memlab analyze unbound-shape
选项:--snapshot-dir 及通用选项。实现:ShapeUnboundGrowthAnalysis.ts
memlab analyze string:查找堆中的重复字符串实例
memlab analyze string
选项:--snapshot 及通用选项。实现:StringAnalysis.ts
memlab analyze unmounted-fiber-node:获取已卸载的 React Fiber 节点
memlab analyze unmounted-fiber-node
选项:--snapshot、--output(text/json,默认 text)及通用选项。实现:UnmountedReactFiberNodesAnalysis.ts
memlab heap:交互式探索单个堆快照
memlab heap 进入交互模式,可在一个堆快照内探索节点、边和保留关系。
memlab heap --snapshot <HEAP_SNAPSHOT_FILE>
选项:--snapshot、--engine(默认 V8)、--heap-parser-dict-fast-store-size(默认 5,000,000)及通用选项。
memlab view-heap:交互式查看单个堆快照
memlab view-heap 以更侧重浏览的方式交互式查看单个堆快照。
memlab view-heap --snapshot <HEAP_SNAPSHOT_FILE>
选项:--snapshot、--engine(默认 V8)、--node-id(堆节点 ID)、--ml-clustering(用机器学习对泄漏轨迹聚类)、--work-dir、--heap-parser-dict-fast-store-size(默认 5,000,000)及通用选项。
MISC 命令:测量、预热与工作目录管理
memlab version:查看已安装包版本
memlab 由多个子包组成(core、api、e2e、heap-analysis、cli 等)。此命令列出所有已安装 memlab 包的版本:
memlab version
实现见 GetVersionCommand.ts:它会懒加载注册各子包(避免启动时过多的文件操作),并按包名排序输出 包名@版本号;配合 --verbose 还能显示每个包的安装位置。
memlab list:列出所有测试场景
列出已 onboard(登记)的测试场景(app 与 interaction 名称):
memlab list
实现见 ListScenariosCommand.ts,通过 defaultTestPlanner 获取 app 名及其可用的 interaction 目标并以彩色输出。
memlab reset:重置并初始化所有目录
清空并重建当前 working directory 的全部目录结构:
memlab reset
选项:--work-dir 及通用选项。实现见 ResetDirectoryCommand.ts:先 fileManager.rmWorkDir() 删除旧工作目录,再 fileManager.initDirs() 重建。
memlab measure:measure 模式重复测量堆大小
部分 Web 应用的堆大小在不同运行间存在明显波动,这种波动常掩盖内存泄漏的真实影响。measure 模式通过重复执行同一场景,获得多个 JS 堆大小数据点,帮助判断堆大小的变动是内存问题还是单纯噪声。
memlab measure --scenario <TEST_SCENARIO_FILE>
示例
memlab measure --scenario /tmp/test-scenario.js
memlab measure --scenario /tmp/test-scenario.js --work-dir /tmp/test-1/
选项
| 选项 | 说明 |
|---|---|
--headful |
有头模式启动浏览器(默认 headless) |
--display-leak-outlines |
在有头浏览器中显示泄漏组件轮廓 |
--run-num |
设置运行次数 |
--app |
设置 onboard 的 Web 应用名称 |
--interaction |
设置 onboard 的交互名称 |
--full |
对 E2E 交互的每一步都采集堆快照 |
--skip-snapshot |
跳过采集堆快照 |
--skip-screenshot |
跳过截图 |
--skip-gc |
跳过浏览器内垃圾回收 |
--skip-scroll |
跳过目标页面滚动 |
--skip-extra-ops |
跳过目标页与最终页的额外交互 |
--run-mode |
设置运行模式 |
--local-puppeteer |
通过本地 puppeteer 调试远程浏览器 |
--scenario |
指定测试场景文件路径 |
--chromium-binary |
指定 Chromium 可执行文件 |
--protocol-timeout |
Chromium 连接协议超时(毫秒),默认 180000,堆快照过大时可调大 |
--device |
设置模拟设备类型 |
--user-agent |
设置浏览器 UserAgent |
--disable-xvfb |
禁用 Xvfb |
--disable-web-security |
关闭 Chromium web security |
--rewrite-js |
启用浏览器内 JS 插桩 |
--log-script |
启用浏览器内 JS 拦截与日志 |
--work-dir |
设置当前运行的 working directory |
--help / -h |
打印帮助文本 |
--verbose / -v |
显示更多细节 |
--sc |
开启 continuous test 模式 |
--debug |
开启手动调试 |
--silent / -s |
静默所有终端输出 |
源码实现见 RunMeasureCommand.ts:默认运行次数为 10(见 NumberOfRunsOption.ts,可通过 --run-num 覆盖),循环调用 runPageInteractionFromCLI(),每次运行都处于 measure 运行模式。
memlab warmup:预热目标应用
在正式分析前预热目标应用,减少冷启动对测量结果的影响:
memlab warmup --scenario <TEST_SCENARIO_FILE>
示例
memlab warmup --scenario /tmp/test-scenario.js
选项:--headful、--display-leak-outlines、--app、--interaction、--run-mode、--local-puppeteer、--scenario、--chromium-binary、--protocol-timeout(默认 180000)、--device、--user-agent、--disable-xvfb、--disable-web-security、--skip-warmup(跳过预热 Web 服务器)、--rewrite-js、--log-script、--work-dir 及通用选项。实现见 WarmupAppCommand.ts,内部调用 @memlab/api 的 warmup()。
memlab help:列出全部命令或查看单个命令帮助
memlab help <COMMAND> [SUB-COMMANDS]
不带参数时列出全部命令分类;带命令名时打印该命令的完整文档、示例与全部选项。实现见 HelperCommand.ts,它按 CommandCategory(COMMON / MISC / DEV)分组展示,内部命令(如 init-dir)默认隐藏、--verbose 时显示;选项说明来自各选项的 getDescription()。
memlab get-default-work-dir:查询默认工作目录
memlab get-default-work-dir
直接打印默认 working directory 路径。实现见 QueryDefaultWorkDirCommand.ts。
memlab snapshot:交互并采集堆快照
驱动浏览器按场景交互并采集堆快照(不做泄漏分析):
memlab snapshot --scenario <TEST_SCENARIO_FILE>
示例
memlab snapshot --scenario /tmp/test-scenario.js
memlab snapshot --scenario /tmp/test-scenario.js --work-dir /tmp/test-1/
选项:--headful、--display-leak-outlines、--app、--interaction、--full、--skip-snapshot、--skip-screenshot、--skip-gc、--skip-scroll、--skip-extra-ops、--run-mode、--local-puppeteer、--scenario、--chromium-binary、--protocol-timeout(默认 180000)、--device、--user-agent、--disable-xvfb、--disable-web-security、--rewrite-js、--log-script、--worker、--work-dir 及通用选项。实现见 TakeSnapshotCommand.ts。
memlab warmup-and-snapshot:预热服务器并采集堆快照
等价于依次运行 memlab warmup 和 memlab snapshot:
# 指定测试场景文件,memlab 将预热服务器并采集堆快照
memlab warmup-and-snapshot --scenario <TEST_SCENARIO_FILE>
示例
memlab warmup-and-snapshot --scenario /tmp/test-scenario.js
# 设置当前运行的 working directory
memlab warmup-and-snapshot --scenario /tmp/test-scenario.js --work-dir /tmp/test-1/
选项:--work-dir、--headful、--display-leak-outlines、--app、--interaction、--run-mode、--local-puppeteer、--scenario、--chromium-binary、--protocol-timeout(默认 180000)、--device、--user-agent、--disable-xvfb、--disable-web-security、--skip-warmup、--rewrite-js、--log-script、--full、--skip-snapshot、--skip-screenshot、--skip-gc、--skip-scroll、--skip-extra-ops、--worker 及通用选项。其前置命令链正是 WarmupAppCommand.ts 与 TakeSnapshotCommand.ts(见 WarmupAndSnapshotCommand.ts)。
通用选项:所有命令共享的开关
以下选项对所有命令通用(定义于 UniversalOptions.ts,由 Dispatcher.parseOptions 统一解析):
| 选项 | 说明 |
|---|---|
--help / -h |
打印帮助文本 |
--verbose / -v |
显示更多细节 |
--sc |
开启 continuous test 模式(设置 config.isContinuousTest = true,见 SetContinuousTestOption.ts) |
--debug |
开启手动调试(设置 config.isManualDebug = true,见 DebugOption.ts) |
--silent / -s |
静默所有终端输出 |
高频选项的底层原理
--leak-filter:自定义泄漏判定规则
--leak-filter 接受一个 JS 定义文件,覆盖默认的泄漏判定逻辑。解析见 LeakFilterFileOption.ts:设置 config.externalLeakFilter = utils.loadLeakFilter(file)。仓库提供了可直接参考的过滤器示例 packages/e2e/static/example/leak-filters/filter-by-retained-size.js,其内部规则类体系位于 packages/core/src/lib/leak-filters/rules。
--heap-parser-dict-fast-store-size:缓解快照解析 OOM
该选项控制堆快照解析器中字典从 fast store 切换到较慢 store 的尺寸阈值,默认 5,000,000,合法取值范围为 1, 10,000,000](见 [HeapParserDictFastStoreSizeOption.ts)。解析超大快照时若报 FATAL ERROR: invalid table size Allocation failed - JavaScript heap out of memory,调低此阈值通常能避免崩溃。
--snapshot-dir 与 --engine
--snapshot-dir 需要目录真实存在,否则直接终止(见 SnapshotDirectoryOption.ts)。--engine 默认 V8,可用值由 constant.supportedEngines 决定,非法值会被拒绝(见 JSEngineOption.ts)。
--ml-clustering 与启发式聚类的取舍
默认情况下泄漏轨迹按启发式规则聚类;--ml-clustering 切换为机器学习算法(见 MLClusteringOption.ts)。在 CheckLeakCommand.ts 中,若用户未显式指定该选项,命令会临时恢复默认设置并在分析结束后还原,避免影响其他运行。
命令调度机制速览
理解 CLI 的整体结构有助于组合使用命令:
- 命令 = 类:每条命令都是继承 BaseCommand 的类,通过
getCommandName()定义命令名、getDescription()定义描述、getOptions()定义支持的选项、getPrerequisites()声明前置命令、getSubCommands()声明子命令。 - 自动注册:CommandLoader.ts 递归扫描
commands目录,凡文件名以Command.js结尾且继承BaseCommand的模块都会注册为可用命令。 - 前置命令链:Dispatcher.ts 在执行某条命令前先递归执行其全部前置命令,且保证每条命令只执行一次;例如
memlab run=init-dir+snapshot+find-leaks的组合,这也是为什么memlab run结束后可以立即用memlab find-leaks --work-dir复用其产物。 - 子命令分派:
memlab analyze <PLUGIN_NAME>的子命令由 runSubCommandIfAny 匹配分发。
典型工作流串联
结合以上命令,一条完整的内存泄漏排查链路可以是:
# 1. 初始化目录(可选,命令会自动执行)
memlab init-dir --work-dir /tmp/memlab-work/
# 2. 运行 E2E 场景,采集快照并检测泄漏
memlab run --scenario /tmp/test-scenario.js --work-dir /tmp/memlab-work/ --headful --display-leak-outlines
# 3. 复跑泄漏分析(复用 work-dir 产物)
memlab find-leaks --work-dir /tmp/memlab-work/
# 4. 查询某个堆节点的保留路径
memlab trace --node-id=@3123123 --work-dir /tmp/memlab-work/
# 5. 对泄漏快照做专项分析(例如 detached DOM)
memlab analyze detached-DOM --snapshot /tmp/memlab-work/data/cur/target.heapsnapshot
# 6. 匿名化快照后分享给同事
memlab anonymize --snapshot /tmp/memlab-work/data/cur/target.heapsnapshot --output /tmp/target-anonymized.heapsnapshot --audit-only
说明:上述
init-dir为内部命令,日常使用中会被自动执行;--work-dir的默认值与memlab get-default-work-dir的输出一致。更多端到端用法可参阅 docs/guides/03-find-leak.md 与 docs/guides/01-detached-dom.mdx。
小结
MemLab CLI 围绕"采集快照 → 分析泄漏 → 定位根因"设计:run、snapshot、warmup、measure 负责在真实浏览器中产生数据;find-leaks、diff-leaks、trace、analyze 负责对快照做离线分析;anonymize 解决分享前的数据脱敏;heap、view-heap 提供交互式探索。掌握每条命令的选项语义(尤其是 --work-dir、--leak-filter、--trace-all-objects、--heap-parser-dict-fast-store-size 与 --ml-clustering),即可将 MemLab 无缝嵌入日常开发与 CI 流程,系统性地发现并修复前端内存泄漏。