堆快照采集
从 Lynx 4.5 开始,Android、iOS 和 HarmonyOS 可以通过 LynxView.takeHeapSnapshot 采集主线程 runtime(MTS)、页面后台 runtime(BTS)分量或 BTS 整体 VM 的堆快照,也可以通过静态接口 LynxView.takeBtsResidualHeapSnapshot 采集已销毁页面的 BTS 残留。
快照保存为 JSON 文件,用于分析 JavaScript 对象及其引用链。建议使用 .heapsnapshot 扩展名;快照不包含 Element tree 或原生 UI/View 对象图。
快照类型
takeHeapSnapshot 通过 type 选择采集范围:
这些接口当前需要 QuickJS 快照能力。V8、JSVM、JSC 等其他引擎不能通过这些接口采集快照。
采集前准备
采集存活页面时,应在页面完成 runtime 初始化后调用,并保持页面存活。MTS 不可用时不能采集 mts,BTS 不可用时不能采集 bts_page 或 bts_vm。
共享 VM 的 bts_page 和已销毁页面残留需要在创建页面或 VM 前启用内存监控,让页面获得可归因的跟踪 slot。通过宿主的 memory_monitor_config 配置入口设置:
进程必须被全局采样选中;采样率小于 1 时并不能保证可用。已有 VM 不会因晚设置配置而补建 slot 跟踪。UI 采样率不影响 JavaScript 堆快照。
mts、bts_vm 和独立 VM 的 bts_page 不依赖页面 slot 跟踪,无需为这些模式单独开启内存监控。
采集存活页面
以下示例假设 lynxView 为已加载页面;Android 的 context 为宿主 Context,HarmonyOS 的 context 为宿主 UIAbilityContext。示例采集 bts_page,可将 type 替换为 mts 或 bts_vm。
Android
接口签名为 void takeHeapSnapshot(File outputFile, LynxConsumer<String> callback, String type)。
iOS
接口为 - (void)takeHeapSnapshot:(nonnull NSString *)outputFile callback:(void (^ _Nullable)(NSString * _Nullable error))callback type:(nonnull NSString *)type。
HarmonyOS
接口返回 void。三个平台均异步采集,不直接返回快照内容。
回调约定
存活页面和已销毁页面残留接口使用相同的回调约定:
Android 和 iOS 支持从任意线程发起调用;iOS 会将存活 View 的访问转移到主线程。采集任务在所属 runtime 线程执行,文件写入由后台 IO 任务完成。
采集已销毁页面残留
页面销毁后,使用静态 takeBtsResidualHeapSnapshot,不再调用原 View 的存活页面接口。该接口不需要 type,只采集目标已销毁页面在共享 QuickJS VM 中的残留分量。
采集需要同时满足:
- 当前进程已启用内存监控。
- 页面在销毁前被跟踪,销毁记录仍可用,且具有有效的页面 slot;
unknown、common、overflow等保留 slot 不适用。 - 页面所用共享 QuickJS VM 仍存活,并可执行采集任务。
应在页面销毁前保存实例 ID,或从全局内存查询的 destroyedInstances[].instanceId、高内存事件的页面或 slot instance_id 获取。不要使用页面 URL、page key、runtime ID 或 group ID 代替实例 ID。
以下示例假设宿主已保存目标 ID 为 savedInstanceId,且目标页面已经销毁。
Android
接口签名为 static void takeBtsResidualHeapSnapshot(File outputFile, LynxConsumer<String> callback, int instanceId)。
iOS
接口为 + (void)takeBtsResidualHeapSnapshot:(nonnull NSString *)outputFile callback:(void (^ _Nullable)(NSString * _Nullable error))callback instanceId:(int32_t)instanceId。
HarmonyOS
接口为静态方法,返回 void。如果 GC 后目标 slot 已无残留,采集仍可能成功并输出空对象图;空图不等同于接口失败。
采集与文件语义
- 快照采集会触发目标 VM 的 GC,并清理引擎持有的 console 消息。它可能影响内存水位和运行耗时,适合按需诊断,不适合高频轮询。全局内存查询本身不会触发 GC。
- 采集会输出运行时诊断摘要,并在可用时记录对象源码位置。源码信息缺失不代表快照失败。
- 快照先在内存中生成,再异步写入文件。只有完整写入成功后,回调才返回无错误。
- SDK 不创建父目录。输出文件已存在时,其内容会被覆盖;采集阶段失败不会改写原文件,写入阶段失败可能留下部分内容。
- 发起请求后,页面或 runtime 的销毁可能导致任务无法执行。以回调结果判断是否获得可用文件;失败时不要直接分析旧文件。
错误处理
失败时,回调返回错误字符串。常见错误如下:
排查建议
先通过全局内存查询或高内存事件定位实例和 runtime 类型。MTS 偏高时使用 mts;页面 BTS 分量偏高时使用 bts_page;需要查看共享对象、其他页面或 VM 整体保活关系时使用 bts_vm。
退出页面并等待正常清理后,如果销毁记录仍显示 BTS 残留,可以按该实例 ID 采集残留快照,分析 GC 后对象的引用链。比较多次快照时,应保持采集范围和监控配置一致。残留字节数或某次快照中仍有对象本身不能直接证明泄漏,需要结合对象生命周期和保活路径判断。