memlab 命令行完全指南:从内存泄漏检测到堆快照分析的 CLI 命令全解

原创2026-10-13 09:02:33944 阅读
文章标签:开发工具测试CLIMCP 服务

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 不依赖浏览器,直接对已采集的堆快照文件做泄漏检测。它有三种指定输入的方式:

  1. --baseline、--target、--final 分别指定三份堆快照文件;
  2. --snapshot-dir 指定包含三份快照的目录(MemLab 按文件名的字母序自动分配 baseline、target、final);
  3. --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 流程,系统性地发现并修复前端内存泄漏。

登录后查看全文
memlab