mem-analyzer 使用手册
资源泄漏日志抓取与分析工具的完整命令行使用说明
安装
Windows
解压 mem-analyzer-{version}-win64.zip，通过命令行运行 mem-analyzer.exe 。
macOS
解压 mem-analyzer-{version}-macos.zip，参考 macOS运行mem-analyzer。
Linux
解压 mem-analyzer-{version}-linux.tar.gz，通过命令行运行 mem-analyzer。
真机演示
以下为真机演示场景，通过视频展示各场景的完整操作流程。
场景一：根据ArkTS快照日志分析组件泄漏和TOP引用链
# 选择 -o 参数，自动生成 HTML 分析报告，并在默认浏览器中打开
mem-analyzer jsleak ~/Downloads/hidumper-jsheap-63074-63074-1787051285526.rawheap -o
支持分析单个堆快照文件，也可同时导入 jsleaklist 文件，进行组件泄漏和 TOP 引用链分析
场景二：导出ArkTS快照日志分析组件泄漏和TOP引用链
# 支持按应用名匹配已安装应用，例如：泄漏演示（包名 com.example.memoryleakapplication）
mem-analyzer profiler 泄漏演示 -c snapshot -o
支持直接导出ArkTS快照日志文件并分析组件泄漏和TOP引用链
场景三：抓取NativeHeap内存泄漏日志并分析TOP函数与调用链
# 如果应用未启动，会自动拉起应用并采集 htrace 日志
mem-analyzer profiler 泄漏演示 -c nativeheap -o
自动拉起应用并采集 htrace 日志，问题复现后可通过 Ctrl+C 退出采集并自动化分析，结束后自动打开分析报告
场景四：抓取ArkTS Handle泄漏日志并分析GlobalHandle与LocalHandle泄漏
# 采集 local handle 日志时，会自动重启应用并采集
mem-analyzer profiler 泄漏演示 -c handle -o
自动重启应用并采集 handle 日志，问题复现后可通过 Ctrl+C 退出采集并自动化分析，结束后自动打开分析报告
命令总览
mem-analyzer [全局选项] [子命令] [子命令选项] <文件...>
采集类
| 子命令 | 别名 | 用途 |
|---|---|---|
profiler |
prof |
通过hdc，从连接的设备实时采集ArkTS堆快照 / htrace / ArkTS句柄日志 |
分析类
| 子命令 | 别名 | 用途 |
|---|---|---|
| （不指定） | — | 根据输入文件类型，自动选择子命令进行分析，并输出分析结果 |
trace |
tr |
分析nativeheap/dma/fd/ashmem类型的内存维测日志（.htrace） |
tshandle |
th |
分析 ArkTS 句柄日志（.zip） |
jsleak |
jl |
分析 ArkTS堆快照（.heapsnapshot/.rawheap） |
全局选项
以下选项可用于大部分的子命令：
| 选项 | 说明 |
|---|---|
-d, --out-dir DIR |
输出目录，默认 out |
-p, --parse-only |
仅解析，跳过分析 |
-o, --auto-open |
处理完成后自动打开结果文件 |
-f, --format FORMAT |
输出格式：json 或 html |
-v, --version |
显示版本信息并退出 |
-h, --help |
显示帮助信息 |
子命令
资源日志采集
profiler — 资源日志采集
mem-analyzer profiler <bundle> [选项]
注意：
profiler不分析本地文件，而是通过hdc连接 HarmonyOS 设备，实时采集目标进程的内存数据（快照 / htrace / 句柄日志），并按需对采集结果自动生成分析报告。
运行前置条件：
- 已安装 HarmonyOS SDK 工具链，且
hdc已加入PATH（可用hdc version验证）。 - 设备已通过 USB 连接、开启 USB 调试（可用
hdc list targets验证）。 - 设备 API 版本满足采集类型要求：
snapshot需 ≥ 24，其他需 ≥ 26。 - 采集目标必须是设备上已安装的应用。
必选选项：
| 选项 | 说明 |
|---|---|
<bundle> |
目标应用/进程名（包名或应用名匹配），--list-apps 时不需要 |
采集类型：
| 选项 | 说明 |
|---|---|
-c, --category TYPE |
采集类型，默认 nativeheap。可选值：nativeheap/nh/native、snapshot/snap、globalhandle/global/gh、allhandle/handle/ah、localhandle/local/lh、fd、dma、thread、ashmem |
可选选项：
| 选项 | 说明 |
|---|---|
-t SECONDS |
采集时长（秒），默认 120 |
-d, --out-dir DIR |
输出目录，默认 out |
-S, --so-dir DIR |
native .so 符号表目录，离线符号化（除 snapshot 外所有采集类型生效） |
--sourcemap PATH |
指定工程 sourceMap 文件或目录（含 sourceMaps.map），生成报告前先还原混淆的编译产物路径为源码路径（仅 snapshot 类型生效） |
--namecache PATH |
指定工程 nameCache 文件或目录（含 nameCache.json），生成报告前先还原混淆的函数/属性名为原始名（仅 snapshot 类型生效） |
-o, --auto-open |
采集完成后自动生成 HTML 分析报告，并在默认浏览器中打开 |
--list-apps |
列出设备上已安装的应用后退出 |
-o与反解参数的联动：-o采集结束后会按采集类型自动派发分析报告——nativeheap/fd/dma/thread/ashmem走trace，globalhandle/allhandle/localhandle走tshandle，snapshot走jsleak。此时-S/--so-dir（native.so反解）会透传给trace/tshandle报告，--sourcemap/--namecache（ArkTS 反混淆）会透传给jsleak报告。
进程名解析：
<bundle>支持传入包名或应用名匹配。若匹配到多个应用会列出候选并要求提供更精确的名称。可先用mem-analyzer profiler --list-apps查看设备上的应用列表。
采集类型详情：
| 值 | 缩写 | 说明 | 对端设备的API等级要求 |
|---|---|---|---|
snapshot |
snap |
采集 ArkTS 虚拟机堆内存快照 | >=24 |
nativeheap |
nh, native |
采集 native heap 堆内存分配 | >=26 |
globalhandle |
global, gh |
采集ArkTS全局句柄（Global Handle）分配 | >=26 |
localhandle |
local, lh |
采集ArkTS局部句柄（Local Handle）分配 | >=26 |
allhandle |
handle, ah |
采集ArkTS局部 & 全局句柄（Local & Global Handle）分配 | >=26 |
fd |
— | 采集文件描述符（fd）分配 | >=26 |
dma |
— | 采集 DMA（ion）内存分配 | >=26 |
thread |
— | 采集线程创建/销毁栈 | >=26 |
ashmem |
— | 采集匿名共享内存（ashmem）分配 | >=26 |
采集流程说明：
- 应用运行状态检测：
- 对
nativeheap/global/fd/dma/thread/ashmem类型，若目标应用未运行，采集前，工具会通过aa start自动拉起。 - 对
local类型，由于需要应用冷启动才能追踪到局部句柄分配，工具会在就绪后重启目标应用，然后再进行采集。 - 对
snapshot类型，需要应用已提前运行，否则无法抓取
- 对
- 启动采集：
- 工具通过hdc命令，启动htrace/ArkTS snapshot/ArkTS句柄维测抓取。
- 在采集过程中，轮询采集状态，等待采集结束
- 采集期间可按
Ctrl+C（macOS 为 Control+C）提前停止，工具会正常结束 hiprofiler 会话并保存已采集的数据。
- 采集完成：
- 收集并拉取维测日志到PC上，按需启动分析流程
使用示例：
# 列出设备上已安装的应用
mem-analyzer profiler --list-apps
# 采集 native heap 堆内存（默认类型）分配栈 60 秒
mem-analyzer profiler -t 60 com.example.app
# 采集 ArkTS 虚拟机堆快照（目标应用需已运行）
mem-analyzer profiler -c snap com.example.app
# 采集ArkTS局部 & 全局句柄分配栈，并自动生成 HTML 报告
mem-analyzer profiler -o -c lh com.example.app
# 采集文件描述符分配栈
mem-analyzer profiler -c fd com.example.app
# 采集线程创建/销毁栈
mem-analyzer profiler -c thread com.example.app
# 采集匿名共享内存分配栈
mem-analyzer profiler -c ashmem com.example.app
输出结构：
采集结果按关键导出文件的名称嵌套在 out/<result>/ 下（与分析子命令一致）。
out/<result>/
├── <采集文件> # .htrace / .zip / .rawheap（取决于采集类型）
├── smaps_<timestamp>.txt # smaps日志（nativeheap/global/local/dma/thread/ashmem）
├── fds_<timestamp>.txt # fd列表日志（fd）
└── <result>.html # 仅当指定 -o 时生成的分析报告
输出说明：
| 采集类型 | 采集产物 | |
|---|---|---|
snapshot |
hidumper-jsheap-* 堆快照 |
|
nativeheap |
mem_analyzer_hiprofiler_data_*.htrace |
|
global / local |
hiprofiler_data_*.zip |
|
fd |
mem_analyzer_hiprofiler_data_*.htrace |
|
dma |
mem_analyzer_hiprofiler_data_*.htrace |
|
thread |
mem_analyzer_hiprofiler_data_*.htrace |
|
ashmem |
mem_analyzer_hiprofiler_data_*.htrace |
注意：
-o会调用同目录下的mem-analyzer二进制对采集结果执行对应分析子命令，并在分析成功后自动打开 HTML 报告。若采集内容为空，则不会生成 HTML。
资源日志分析
1. 自动检测模式
不指定子命令时，mem-analyzer 会自动检测文件类型并处理。
mem-analyzer [全局选项] <文件...>
# 自动检测&分析 .htrace 文件的nativeheap信息
mem-analyzer profile.htrace
# 自动检测&分析 .htrace 文件的nativeheap信息，并且自动打开结果文件
mem-analyzer -o profile.htrace
# 自动检测&分析 .heapsnapshot 文件
mem-analyzer snapshot.heapsnapshot
# 自动检测&分析 .zip 文件的ArkTS句柄信息
mem-analyzer handle_data.zip
2. jsleak — ArkTS 堆日志分析
mem-analyzer jsleak [选项] <输入文件>
注意：
jsleak根据文件扩展名判断输入类型：.rawheap结尾的文件会先转换为 heapsnapshot 再解析；其他扩展名直接视为 heapsnapshot 处理。
专属选项：
| 选项 | 说明 |
|---|---|
-n, --top-n N |
输出 Top N 引用链，默认 10 |
-l, --leaklist FILE |
泄漏定义文件（.jsleaklist）路径 |
-m, --mode MODE |
分析模式：all（默认）、property-tag/pt、top-chain/tc |
--sourcemap PATH |
指定工程 sourceMap 文件或目录（含 sourceMaps.map），用于将混淆的编译产物路径还原为源码路径 |
--namecache PATH |
指定工程 nameCache 文件或目录（含 nameCache.json），用于将混淆的函数/属性名还原为原始名 |
-o, --auto-open |
分析完成后自动打开结果文件 |
输入文件：.heapsnapshot 或 .rawheap 文件。
使用示例：
# 分析堆快照
mem-analyzer jsleak snapshot.rawheap
# 分析堆快照，完成后直接打开结果文件
mem-analyzer jsleak -o snapshot.rawheap
# 指定 Top-N 和泄漏定义文件
mem-analyzer jsleak -n 20 -l my_leaks.jsleaklist snapshot.heapsnapshot
# 仅属性标签分析
mem-analyzer jsleak -m pt snapshot.heapsnapshot
# 仅最短引用链分析
mem-analyzer jsleak -m tc snapshot.heapsnapshot
# 反混淆分析：使用工程 sourceMap 与 nameCache 归档目录，将混淆的函数名/属性名与编译产物路径还原为原始名/源码路径后分析
mem-analyzer jsleak --sourcemap <PATH> --namecache <PATH> snapshot.heapsnapshot
反混淆说明：指定
--sourcemap或--namecache时，解析前先在系统临时目录中对快照做还原（将混淆的函数名/属性名与编译产物路径还原为原始名/源码路径与行号）；还原成功则基于还原后的快照内容解析与分析，临时产物随命令结束自动清理，不写入--out-dir（默认out）——out下仅生成最终报告。未指定时行为与之前完全一致。若索引目录不存在，或目录内缺少对应索引文件（如无sourceMaps.map/nameCache.json），仅打印告警并继续分析未还原的快照。
输出结构：
out/<filename>/
└── <filename>.html
输出说明：
| 输出 | 说明 |
|---|---|
<name>.html |
交互式 HTML 报告，含类层级、保留大小和引用链 |
3. tshandle — ArkTS 句柄日志分析
mem-analyzer tshandle [选项] <文件...>
注意：
tshandle子命令忽略文件扩展名，默认将输入内容视为 ZIP 格式进行处理。
专属选项：
| 选项 | 说明 |
|---|---|
-d, --out-dir DIR |
输出目录，默认 out |
-p, --parse-only |
仅解析，跳过分析 |
-f, --format FMT |
输出格式：json 或 html |
-S, --so-dir DIR |
native .so 符号表目录，用于 htrace 离线符号化，缺省不反解 |
--sourcemap PATH |
sourceMap 文件或目录，用于还原 ArkTS 混淆路径/行号（缺省不还原） |
--namecache PATH |
nameCache 文件或目录，用于还原 ArkTS 混淆名称（缺省不还原） |
-o, --auto-open |
分析完成后自动打开结果文件 |
输入文件： .zip 文件，通常包含：
*.htrace— 内存分配栈数据（必需，否则报错退出）*.rawheap— 原始堆快照（可选，缺失时跳过 ArkTS 类分析）*.binpb/*.txt— 地址映射文件（可选，缺失时跳过 ArkTS 类分析）
使用示例：
# 生成完整分析 HTML 报告
mem-analyzer tshandle handle_data.zip
# 解析句柄数据为 JSON（含调用栈和 ArkTS 类分析）
mem-analyzer tshandle --parse-only -f json handle_data.zip
输出结构：
out/<filename>/
└── <filename>.html # 或 .json
输出说明：
| 模式 | 格式 | 输出内容 |
|---|---|---|
| 分析模式 | html |
交互式 HTML 报告，含句柄类型分析、类表格、调用图 |
--parse-only |
json |
调用栈、ArkTS 类实例、nativeRef 条目、内存摘要 |
4. trace — htrace日志分析
mem-analyzer trace [选项] <文件...>
注意：
trace子命令忽略文件扩展名，默认将输入内容视为 htrace 格式进行处理。
专属选项：
| 选项 | 说明 |
|---|---|
-c, --category CAT |
资源类别：nativeheap（默认）、mmap-anon、dma、ashmem、fd、thread |
-s, --scope SCOPE |
分析范围：app-only、system-only、app-and-system（默认）、mixed |
-n, --top-n N |
报告中显示 Top N 符号，默认 10 |
-S, --so-dir DIR |
native .so 符号表目录，用于离线符号化，缺省不反解 |
-o, --auto-open |
分析完成后自动打开结果文件 |
-s, --scope 详细说明：
控制 Top 符号列表中包含哪些层级的符号，用于聚焦特定层级的泄漏分析：
| 值 | 说明 | 适用场景 |
|---|---|---|
app-only |
仅显示应用层符号（如 libentry.so、libace.so） |
排查应用自身的内存泄漏 |
system-only |
仅显示系统层符号（如 libc.so、libskia.so） |
排查系统库或框架层泄漏 |
app-and-system |
同时显示应用层和系统层符号（默认） | 全面分析，不区分层级 |
mixed |
显示跨层混合符号（调用链同时涉及应用和系统层） | 排查应用与系统交互导致的泄漏 |
注意：
-s仅在分析模式（非--parse-only）下生效。--parse-only模式会输出全部资源类型的调用栈，不受 scope 影响。
资源类别说明：
| 值 | 说明 |
|---|---|
nativeheap |
nativeheap堆内存分配（malloc/free） |
dma |
DMA/ION 内存分配 |
ashmem |
匿名共享内存 |
fd |
文件描述符分配 |
thread |
线程创建/销毁 |
使用示例：
# 分析nativeheap堆，默认生成 HTML 交互报告
mem-analyzer trace -c nativeheap profile.htrace
# 分析 DMA 内存，显示 Top 20 符号
mem-analyzer trace -c dma -n 20 dma_profile.htrace
# 分析文件描述符
mem-analyzer trace -c fd -f html fd_profile.htrace
# 仅分析应用层分配
mem-analyzer trace -c nativeheap -s app-only profile.htrace
# 仅解析，提取所有调用栈到 JSON
mem-analyzer trace -p profile.htrace
输出结构：
out/<filename>/
├── <filename>.json # 或 <filename>.html
输出说明：
| 模式 | 格式 | 输出内容 |
|---|---|---|
--parse-only |
json |
所有调用栈（含解析后的符号、库名、build ID） |
| 分析模式 | json |
统计摘要、Top 符号、火焰图数据 |
| 分析模式 | html |
交互式 HTML 报告，含火焰图、冰柱图和调用栈表格 |
注意：
--parse-only模式下-c参数不影响输出（会输出全部资源类型的调用栈）。
支持的文件类型
| 扩展名 | 对应子命令 | 说明 |
|---|---|---|
.htrace |
trace |
Hiprofiler 原生内存追踪 |
.zip |
tshandle |
ArkTS 句柄日志包（htrace + 堆快照） |
.heapsnapshot |
jsleak |
ArkTS 堆快照 |
.rawheap |
jsleak |
原始堆数据（自动转换为 heapsnapshot） |
输出目录结构
指定 -d out 后，输出文件会嵌套在 out/<输入文件名>/ 下，文件名与输入文件相同（仅扩展名变化）。
示例：假设有三个输入文件 native.htrace、handle_data.zip、snapshot.heapsnapshot，输出结构如下：
out/
├── native/ # 目录名 = 输入文件名
│ ├── native.html # 输出文件名 = 输入文件名 + .html
│ └── native.json # 或 .json
├── handle_data/
│ └── handle_data.html
└── snapshot/
└── snapshot.html
说明：native、handle_data、snapshot 仅为示例，实际目录名取决于输入文件名称。
查看版本
mem-analyzer --version
# mem-analyzer version 0.2.5
常用场景
场景一：ArkTS堆快照分析
# 1. 分析并生成html报告
mem-analyzer app.rawheap
# 2. 分析并生成html报告，显示 Top 20 符号
mem-analyzer jsleak -n 20 snapshot.heapsnapshot
# 3. 分析并生成html报告，并自动打开结果文件
mem-analyzer jsleak -o snapshot.heapsnapshot
场景二：ArkTS 句柄日志分析
# 1. 分析 zip 包，分析并生成html报告
mem-analyzer handle_data.zip
# 2. 分析并生成html报告，显示 Top 20 符号
mem-analyzer tshandle -n 20 handle_data.zip
# 3. 分析并生成html报告，并自动打开结果文件
mem-analyzer -o handle_data.zip
场景三：htrace日志文件分析
# 1. 分析nativeheap, 生成html报告
mem-analyzer leak.htrace
# 2. 分析dma, 生成html报告
mem-analyzer trace -c dma -f html leak.htrace
# 3. 分析nativeheap，且仅显示应用层的Top符号
mem-analyzer trace -s app-only leak.txt
# 4. 分析并生成html报告，并自动打开结果文件
mem-analyzer -o leak.htrace
场景四：提取htrace调用栈数据进行二次分析
# 输出 JSON 格式的原始调用栈数据
mem-analyzer -p data.htrace
# 后处理 out/data/data.json
场景五：资源日志采集并一键分析
# 1. 确认设备已连接
hdc list targets
# 2. 采集目标应用60S的nativeheap堆分配，生成分析报告，并自动打开
mem-analyzer profiler -c nh -t 60 -o com.example.app
# 3. 采集目标应用的堆快照，生成分析报告，并自动打开
mem-analyzer profiler -c snapshot -o com.example.app
macOS运行mem-analyzer
受限于权限管理，在macOS上运行，需授权运行mem-analyzer，或者自行编译运行。
方式1：移除隔离属性
- 下载发布的mem-analyzer二进制文件
- 解压二进制文件到任意目录，例如
~/Documents/mem-analyzer/ - 打开“终端”，切换到解压目录，移除隔离属性
cd ~/Documents/mem-analyzer/
# 递归移除隔离属性，包括子目录中的文件
xattr -rd com.apple.quarantine ./
方式2：授权运行mem-analyzer
- 下载发布的mem-analyzer二进制文件
- 解压二进制文件到任意目录，例如
~/Documents/mem-analyzer/ - 打开“终端”，切换到解压目录，运行mem-analyzer
cd ~/Documents/mem-analyzer/
./mem-analyzer
-
首次运行时，会弹出如下提示，点击右上的问号，进入手册页面
-
进入手册页面后，可以看到 “为我打开“隐私与安全性”设置” , 点击此链接，前往系统设置中的“隐私与安全性”设置页面。
-
在系统隐私与安全性设置中的“安全性”设置页面下，可看到 已阻止“mem-analyzer”以保护Mac，点击后面的“仍然允许”。
-
回到终端，重新运行mem-analyzer，会弹出如下提示，选择“仍要打开”
-
弹出如下提示，授权通过后，即可运行
-
由于mem-analyzer在运行时，会调用trace_streamer_mac和rawheap_translator，因此同样需要用户进行上诉的授权流程。
注意：针对单个二进制的授权是永久的；但每次重新下载后，运行新下载的二进制都需要重新授权。
方式3：自行编译运行mem-analyzer，无需授权
- 下载代码到本地目录，例如
~/Documents/mem-analyzer/ - 进入代码目录，例如
~/Documents/mem-analyzer/cpp - 使用脚本编译代码，并手动运行mem-analyzer
# 编译代码，编译脚本会校验环境，提示用户下载依赖项
./relase-mac.sh
# 编译完成后，在cpp目录下有`mem-analyzer-x.x.x-macos-xx`目录，进入该目录，运行mem-analyzer
cd mem-analyzer-x.x.x-macos-xx/
./mem-analyzer
相关文档
| 文档 | 内容 |
|---|---|
| README.md | 项目概述、架构说明、构建指南。(注意版本对应关系) |
| cpp/README.md | C++ 引擎详细文档。(注意版本对应关系) |