资源泄漏排查工具HiDebug：快速定位内存与句柄泄漏

数码系统

相机 win10

测评 win11

手机智车

华为 Tesla

小米理想

苹果蔚来

游戏软件

LOL 抖音

原神微信

当前位置：首页

前端开发

资源泄漏排查工具HiDebug：快速定位内存与句柄泄漏

作者:实验室老王时间：2026-08-13

转载

应用一边运行，一边悄悄上涨资源占用？FD、线程、Native 内存、GPU 内存、Global Handle，到底是谁在“偷偷变胖”？这一次，不再靠经验猜测，也不只是盯着日志反复排查。HarmonyOS 6 1 带来的 HiDebug 资源采集 API，可以直接让调用栈开口说话。适用场景：Harmo

应用一边运行，一边悄悄上涨资源占用？

FD、线程、Native 内存、GPU 内存、Global Handle，到底是谁在“偷偷变胖”？

这一次，不再靠经验猜测，也不只是盯着日志反复排查。HarmonyOS 6.1 带来的 HiDebug 资源采集 API，可以直接让调用栈开口说话。

适用场景：HarmonyOS 应用稳定性建设、线上自诊断、DFX 性能调优、资源泄漏排查与定位。

先说痛点：线上资源问题，往往非常会隐藏

资源调优和资源泄漏排查，是鸿蒙应用开发中高频且棘手的两类问题。

很多时候，开发者先看到的是“现象”：

•应用越跑越卡。

•内存曲线持续上升。

•线程数量在不知不觉中增多。

•FD 数量悄然逼近系统上限。

•GPU 内存或 VM 堆使用率看起来异常。

但如果要进一步回答“是谁分配的”“来自哪条调用链”“为什么一直没有释放”，仅靠流水日志、/proc/[pid]/smaps、/proc/meminfo、/proc/memview、hidumper --mem，通常还差关键证据。

HiDebug 资源采集 API，正是用来补上这一环的。

借助 Performance Analysis Kit 提供的 OH_HiDebug_StartProfiler/OH_HiDebug_StopProfiler，应用可以在合适的时机采集资源分配调用栈。原本只是“怀疑有资源泄漏”，现在可以直接落到“这里有分配证据”。

它能监控哪些资源？

简单来说：FD 泄漏、线程泄漏、Native 内存增长、GPU 内存增长、Global Handle 未释放，都可以纳入监控和分析范围。

核心接口：启动与停止，形成完整闭环

在 HarmonyOS 6.1 中，资源采集接口 API 24.0 的核心原型如下。

一个接口用于选择资源类型并启动采集，另一个接口用于结束采集，最终结果通过回调返回。

// 资源类型typedef enum OH_HiDebug_ResourceType {  OH_RES_TYPE_FD,  OH_RES_TYPE_THREAD,  OH_RES_TYPE_NATIVE,  OH_RES_TYPE_GPU,  OH_RES_TYPE_GLOBAL_HANDLE} OH_HiDebug_ResourceType;// 采集参数typedef struct OH_HiDebug_ResProfilerConfig {  uint32_t maxDuration;  uint32_t filterSize;  uint32_t maxStackDepth;  uint32_t statisticsInterval;  uint32_t sampleInterval;} OH_HiDebug_ResProfilerConfig;// 采集结果typedef struct OH_HiDebug_ProfilingResult {  OH_HiDebug_ResourceType resourceType;  const char* filePath;} OH_HiDebug_ProfilingResult;// 采集结果回调函数typedef void (*OH_HiDebug_ProfilingCallback)(OH_HiDebug_ProfilingResult* result);// 启动采集HiDebug_ErrorCode OH_HiDebug_StartProfiler(  OH_HiDebug_ResourceType type,  OH_HiDebug_ResProfilerConfig* config,  OH_HiDebug_ProfilingCallback callback);// 停止采集HiDebug_ErrorCode OH_HiDebug_StopProfiler(void);

复制代码

type：先决定要抓哪一类资源

type 参数用于选择采集的资源类型，当前支持以下五类：

•OH_RES_TYPE_FD：文件描述符。

•OH_RES_TYPE_THREAD：线程。

•OH_RES_TYPE_NATIVE：Native 内存。

•OH_RES_TYPE_GPU：GPU 内存。

•OH_RES_TYPE_GLOBAL_HANDLE：全局句柄。

你怀疑哪类资源存在异常，就先把分析视角对准哪一类。

config：让采集结果有价值，也尽量减少对用户的影响

config 采集参数支持五种配置项。它们的核心作用，是在“采集精度足够高”和“不要明显拖慢应用”之间做好平衡。

小提醒

采集参数需要结合实际开销灵活调整，目标是在性能损耗与用户体验之间取得自适应平衡。默认值只是参考，并不是所有场景都适用的固定答案。

callback：采集完成后去哪里查看结果

采集完成后，结果会通过 callback 回调返回。

开发者拿到 .htrace文件路径后，可以将文件上传到云侧进行资源泄漏根因分析、聚类分析，或者导入 IDE 查看 Call Trees 调用树。

这一步非常关键：资源问题终于可以从“只能猜”进入“可以查”的阶段。

实现逻辑：本质上是把资源分配路径照亮

资源分配栈采集的核心逻辑，是对不同资源的分配与释放函数进行跟踪，然后记录调用栈、去重、符号化，并最终以 protobuf 格式的 .htrace文件落盘到应用沙箱目录。

不同资源的大致采集逻辑如下：

•FD：hook 文件描述符打开与关闭函数，并记录调用栈。

•线程：hook 线程创建与销毁函数，并记录调用栈。

•NativeHeap：hook musl 库malloc/calloc/realloc/free、mmap/munmap函数，并记录调用栈。

•GPU 内存：hook OpenGLES、Vulkan、OpenCL 的 texture、buffer 创建与释放函数，并记录调用栈。

•Global Handle：hook global handle 对象的创建与释放函数，并记录调用栈。

换句话说，它不只是告诉你“资源涨了”，而是尽可能告诉你“资源是从哪里涨起来的”。

什么时候触发？不要随手开启，要有明确策略

线上采集最重要的一点，就是“该出手时再出手”。

下面是推荐的触发条件，可作为接入策略参考：

注意

当应用 Native 内存超过 4GB，且整机内存压力较大时，可能触发系统管控。实践中建议在超过 3GB 或更低阈值时就提前启动采集，不要等问题完全暴露后再开始排查。

规格约束：能力很强，也有明确边界

HiDebug 资源采集能力非常实用，但它并不是无限制、无限频次的“随便采”能力。

采集配额限制

•整机所有应用共享：每日最多可采集 4 次；同一时刻最高支持 4 个不同应用并行采集。

•单应用独享：每日最多可采集 2 次；同一时刻最高支持应用内 2 个进程并行采集。

系统负载熔断机制

当系统触发以下任一负载保护条件时，API 采集请求可能被拒绝，并返回对应错误码：

•整机系统 CPU 占用率超过 70%。

•整机剩余可用内存 RAM 或剩余可用存储空间 ROM 低于会影响应用体验和整机读写性能的阈值。

负载保护条件可能会随着系统版本迭代持续优化，具体以实际返回错误码为准。

并发冲突约束

本 API 与命令行工具或系统采集任务之间存在排他关系。

当与命令行工具或系统采集任务发生冲突时，API 采集请求会被拒绝，并返回相应错误码。

采集结果交付

•存储路径：采集到的调用栈日志文件会自动保存在应用沙箱目录/data/storage/el2/base/files/。

•文件名规则：资源采集类型-进程名-进程号-时间戳.htrace。

老化管控

每种资源类型都受以下条件约束：

•按文件个数管控：只保留最新 5 份文件，采用滚动老化策略。

•按文件大小管控：单文件上限 1G，达到上限后即停止采集，避免文件过大造成磁盘压力或 IDE 无法加载。

•按目录空间管控：当沙箱下采集文件存储空间超过 4G 时，删除最早生成的采集文件。

•按存储时效管控：单个日志最大存储 24 小时，到期后自动清理。

系统采集模式优先级

•命令行模式hdc shell hiprofiler_cmd优先级更高，可抢占 API 采集、系统采集、应用灰度采集。

•当 API 采集与系统采集、应用灰度采集并发时，按照 FIFO 原则处理，先发起的模式优先响应，其它模式拒绝访问。

再敲一下重点

本 API 不保证每一次采集请求都能成功。调用它会对当前应用进程以及整机性能、功耗产生不可忽略的影响，包括但不限于 CPU、内存占用升高、丢帧卡顿、设备发热。线上环境严禁盲目或高频触发。

推荐接入姿势：更稳妥，也更有效

如果你希望把 HiDebug 资源采集能力接入线上诊断链路，建议遵循以下原则：

1.只在灰度范围内开启，避免影响全部用户。

2.只在资源占用超过业务基线或推荐阈值时触发。

3.采集前先检查系统负载，避免在高压状态下继续增加系统压力。

4.合理配置maxDuration、maxStackDepth、statisticsInterval、sampleInterval。

5.采集完成后及时上传、分析、清理，避免日志文件持续堆积。

6.将.htrace文件与业务场景、版本、设备信息建立关联，方便后续聚类分析与根因定位。

这才是线上诊断的正确打开方式：精准触发、拿到证据、快速闭环。

Global Handle 泄漏：几个常见高频场景

Global Handle 泄漏是 Native 侧非常容易踩到的坑。下面三个示例都很典型，适合作为排查时的“对照样本”。

场景一：全局引用创建后忘记 delete

#include // 全局引用，泄漏高发点static napi_ref g_my_ref = nullptr;napi_value LeakRef(napi_env env, napi_callback_info info){  napi_value obj;  napi_get_cb_info(env, info, nullptr, nullptr, &obj, nullptr);  // 创建强引用，初始计数为 1，但只创建不释放  napi_create_reference(env, obj, 1, &g_my_ref);  return nullptr;}// 应补充清理函数：// void Cleanup(napi_env env)// {//   if (g_my_ref) {//     napi_delete_reference(env, g_my_ref);//     g_my_ref = nullptr;//   }// }

复制代码

这个场景非常常见：创建引用时很顺手，清理释放时却很容易被忽略。

但全局引用不会自行消失，时间一长，就会演变成应用稳定性风险。

场景二：循环或重复创建后不释放

napi_value CreateAndLeak(napi_env env, napi_callback_info info){  napi_value obj;  napi_get_cb_info(env, info, nullptr, nullptr, &obj, nullptr);  napi_ref ref;  // 每次调用都新建引用，但没有 delete  napi_create_reference(env, obj, 1, &ref);  // 如果覆盖旧 ref，旧句柄也会永久丢失  // g_ref = ref;  return nullptr;}

复制代码

单次泄漏看起来并不明显，但如果在循环或高频调用场景中反复发生，问题就会迅速放大。

这类问题尤其适合通过资源分配栈采集来确认真实调用来源。

场景三：类或实例持有引用，析构时没有清理

class NativeHolder {public:  napi_ref m_ref;  NativeHolder(napi_env env, napi_value obj)  {    napi_create_reference(env, obj, 1, &m_ref);  }  // 析构时缺少 napi_delete_reference(env, m_ref)  ~NativeHolder()  {  }};napi_value CreateHolder(napi_env env, napi_callback_info info){  napi_value obj;  napi_get_cb_info(env, info, nullptr, nullptr, &obj, nullptr);  NativeHolder* holder = new NativeHolder(env, obj);  // 若不主动清理：holder 泄漏 + m_ref 泄漏  return nullptr;}

复制代码

当类实例与引用绑定在一起时，生命周期管理更需要谨慎。

对象销毁、引用释放、异常路径回收，都需要成套考虑，不能只处理主流程。