本原创文章帖发布在华为开发者联盟社区，欢迎开发者前往访问评论交流，更多与该内容相关讨论，请点击原帖查看：开发态快速定位ArkTS泄漏-华为开发者话题 | 华为开发者联盟
1.1 ArkTS 内存泄漏分析流程与高频泄漏场景
1.1.1 术语介绍
1.1.2 高频泄漏场景
1.1.2.1 JS 对象被 VMRoot 类型持有导致内存泄漏
常见构成 VMRoot 引用的来源包括：
模块导出对象：export 出的对象被底层的 SourceTextModule 系统对象持有，而模块本身在应用生命周期内不被卸载。
全局对象属性：通过 globalThis.xxx = ... 挂载的对象，globalThis 是贯穿应用始终的根对象。
内置原型链扩展：修改 Array.prototype、Object.prototype 等内置对象原型，导致意外全局持有。
一旦业务对象挂载到上述根节点上，即使页面销毁、组件卸载，该对象依然被 VMRoot 强引用，GC 无法回收。
1.1.2.2 JS 对象被 Local Handle/Global Handle 引用导致内存泄漏
在鸿蒙的 JS-Native 交互中，JS 对象可以通过 NAPI Native 代码访问或持有。Native 代码为了引用这些 JS 对象，会使用两种主要的句柄类型：napi_value、napi_ref。其中，napi_ref 是一种引用计数的句柄，用于保持对 JS 对象的引用，防止其在 Native 代码持有引用期间被垃圾回收器回收。
Local Handle (napi_value): 通常指在 Native 代码执行上下文中创建的、作用域较短的引用。当 Native 代码执行环境切换时，这些 Local Handle 通常会被自动清理。Local Handle 受 Handle Scope 管理，大部分场景下（如同步调用、napi 框架异步调用等）系统会为创建的 Local Handle 添加 Handle Scope，但仍有部分场景（如 libuv 异步调用等）系统不会主动添加 Handle Scope，需要应用自行添加 Handle Scope，否则就会导致 JS 对象无法回收。
Global Handle (napi_ref): 这是一种作用域为整个应用生命周期的引用。一旦创建，除非显式删除，否则它会一直保持对 JS 对象的引用。通常用于需要跨模块、跨上下文甚至跨 JS 线程访问的 JS 对象。由于其持久性，如果不加注意，很容易成为 JS 对象泄漏的根源。
当 Native 代码持有（无论是 local 还是 global）一个 JS 对象时，它实际上建立了一种强引用关系。在 JS 引擎的垃圾回收机制中，如果一个 JS 对象的所有可达性引用（包括 JS 代码内部的引用、DOM 树等）都被清除，该对象就可以被回收。然而，如果存在一个 Native 句柄指向它，那么这个句柄就构成了一个阻止根，使得该 JS 对象在 Native 代码持有该句柄期间，从垃圾回收器的角度看，它是“可达”的。这就阻止了 JS 对象被回收，从而可能导致内存泄漏。
1.1.2.3 JS 对象被 FrameRoot 类型持有导致内存泄漏
正常情况下，函数执行完毕退栈后，栈帧销毁，这些临时引用自动失效，内存随之释放。
然而，若函数长期不退栈，局部变量/参数所引用的对象将持续被 FrameRoot 锚定，即便业务逻辑已不再需要它们，GC 也无法回收。常见导致栈帧滞留的情形包括：
死循环或无限递归，函数永不返回。
在函数内启动了一个长期运行的同步阻塞操作（如同步网络请求、大文件同步读写）。
函数内部创建了闭包并被外部长期持有，且闭包捕获了该函数栈帧中的变量（导致整个栈帧无法释放）。
使用了生成器（Generator）或 async/await 但未正确消费，导致协程挂起，栈帧保留。
1.1.3 标准化排查流程
复现与观察：使用 DevEco Profiler 的 Realtime Monitor(Memory 泳道)，重复多次进出目标页面，观察内存曲线是否呈阶梯状上升。
识别泄漏点：在操作前后各采集一次堆快照，使用 Snapshot 对比功能，关注新增对象数量和 Shallow Size，从而识别泄漏点。
查看对象引用链：在 Snapshot 快照的对象引用链中找到异常存活对象（如本该销毁的 Component 实例），通过“Shortest Paths”分析引用链情况。
是否 VMRoot 持有：若引用链顶端为 VMRoot / SourceTextModule，多为模块导出单例或全局变量未清理。
是否 Local/Global Handle 持有：若泄漏对象的 Distance 为 1，则多为 Native 侧持有未释放导致。可分为 2 种场景：
a. Local Handle：napi_value 未使用 napi_open_handle_scope 或未成对使用（即使用 napi_open_handle_scope 但是未使用 napi_close_handle_scope 释放）
b. Global Handle：napi_ref 未调用 napi_delete_reference 释放或未成对使用（即使用 napi_create_reference 但是未使用 napi_delete_reference 释放）在这 2 种情况下，无法基于引用链分析，需要通过 Allocation 模板，开启 Local Handle 及 Global Handle 录制选项来进一步分析。
是否 FrameRoot 持有：若非 VMRoot 和 Local/Global Handle 持有，则多为函数不退栈或闭包捕获对象被外部持有。
代码审查：根据引用链中的关键节点（如 EventHub、Timer、全局变量、napi_ref、闭包上下文）定位代码中的持有关系。
修复与验证：修改代码后重复步骤 1~2，确认内存曲线回归平稳。
图 1
1.2 ArkTS 内存泄漏分析案例
1.2.1 案例背景
现象：本案例中，通过复现‘首页至消息页’的反复进出操作，观察到应用内存占用呈现"阶梯式持续增长"趋势。在循环操作 10 次后，应用出现显著卡顿现象。
初步判断：典型的“阶梯式内存增长”，高度疑似内存泄漏。
1.2.2 分析流程
1.2.2.1 步骤 1：Memory 泳道确认泄漏
打开 DevEco Studio，连接真机，点击 Profiler 工具 Realtime Monitor（也可使用 snapshot 模板的 Memory 录制观察，以下是使用 Realtime Monitor 观察）。
启动应用，选择设备与应用进程。
点击录制按钮，在设备上重复操作：进入消息页面 → 停留 2 秒 → 返回首页，重复多次。
观察内存曲线：
正常预期：每次退出后内存回落至基线附近，整体呈锯齿状。
实际现象：曲线呈阶梯状上升，多次操作后内存增长至 314.1MB 且无明显回落。
确认存在内存泄漏，进入下一步。
图 2
1.2.2.2 步骤 2：堆快照对比定位异常对象
在 Profiler 中切换到 Snapshot 模板，请参考使用 Snapshot 模板基本操作 ：选择 Profiler 工具 → 选择设备与应用进程 → 选择 Snapshot 模板 → 创建 Session → 启动录制
图 3
抓取快照 1：首次在进入消息页前，点击“Take Heap Snapshot”。
图 4
抓取快照 2：重复进出消息页面 7 次后，回到首页，点击“Take Heap Snapshot”，再抓取第二次快照，并停止录制。
图 5
在快照对比视图 Comparison 中，选择 CompareTo Snapshot1。
图 6
查看对象新增销毁情况，优先关注：
操作次数的整数倍或整数倍+1（export 出的对象本身也有一条引用链），
业务对象，即 Constructor 的结构为包名/模块名/文件路径 #泄漏对象
图 7
关键发现：
对比结果中，Test 对象实例数量从 0 个 增加到 8 个。
正常情况下，页面退出后组件实例应被回收，快照 2 中应只有 1 个 Test 对象（被 export 持有）。
确认 Test 对象实例泄漏。
1.2.2.3 步骤 3：追踪引用链
在快照对比视图中，展开并选中一个 Test 对象实例，优先选 Distance 数量较多的，此处我们选 “6” 的，并打开右侧详细信息面板。
注：选择 Distance 数量较多的对象实例，主要是因为这些实例频繁地被创建且未能得到及时释放。这表明存在潜在的内存泄漏问题，需要进一步调查以确定具体的泄漏源。
图 8
点击 “Shortest Paths” 获得如下 Test 对象实例的最短引用链：
图 9
1.2.2.4 步骤 4：分析 VMRoot 类型持有导致泄漏问题
根据步骤 3 得到的 Test 对象实例的最短引用链分析，该引用链的 GC Root 为 SourceTextModule 符合被 export 模块导出对象持有，VMRoot 泄漏类型场景。
图 10
从 GC Root 向上排查引用链，找到第一个业务对象，即 CacheTest.ts 文件中的 CacheTest 对象的 cache 属性持有了 Test 对象未释放。点击后面跳转图标，打开 CacheTest 对象实例详细面板
图 11
CacheTest 对象实例面板中，点击对象名后跳转按钮，跳转对应代码行。
图 12
跳转代码后分析，CacheTest 对象存在静态属性 cache，该静态属性中保存了 Test 对象。
图 13
结合业务代码分析，MessageCenterPage 组件创建时会保存一个 Test 对象到 CacheTest 中，但组件销毁时未清理该缓存导致内存泄漏。
图 14
修改代码，在页面销毁时清除缓存。修改后重新复现操作 7 次，并抓快照验证，Test 对象创建数量正常。但分析发现 Proxy 对象数量异常，创建 70 个未销毁。
图 15
参考 “步骤 3：追踪引用链” ，找到最短引用链，发现该 Proxy 对象的 Distance 为 1。说明其为 GC Root 直接持有的对象，被 Native 侧直接持有未释放，即 JS 对象被 Local Handle/Global Handle 引用导致内存泄露。
图 16
通过 Proxy 对象的 Distance 为 1 的 References，确认内存泄露是由 JS 对象被 Global Handle 引用导致。
图 17
1.2.2.5 步骤 5：分析 Local Handle/Global Handle 类型持有导致泄漏问题
基于步骤 4 分析得到 Proxy 对象实例可能被 Local Handle/Global Handle 引用导致内存泄露，我们可以通过以下步骤继续分析定位：
配置 Allocation 录制模板并捕获数据
打开 DevEco Studio：确保你的工程已加载，并连接了目标设备或模拟器。
进入 Profiler 模块：在主界面下方菜单栏，找到并点击 Profiler 选项卡。
选择应用进程：运行应用，并在 “区域 2” 选择目标设备和应用进程。
创建 Allocation 录制模板：选择 “Allocation” 并点击 Create Session 创建录制模板
图 18
配置录制参数
配置模式：选择详情模式（即关闭 Statistics Mode）。当前仅详情模式支持进行 ArkTS 和 Native 的关联分析
配置开关： 勾选“Local Handle”和“Global Handle”，这是关键配置。这将使 Allocation 专门捕获与 JS-NAPI 句柄相关的内存分配事件。
如果底层镜像不支持该功能，则会提示“当前镜像版本不支持，请升级镜像”；
图 19
配置泳道范围：勾选 ArkTS Snapshot 泳道。这将使 Allocation 在录制结尾时自动抓取一份 Snapshot 快照用于关联分析。
图 20
启动录制：勾选了“Local Handle”开关后，如果是在应用本生命周期内首次录制 local handle 数据，会触发弹窗请求重启应用以便录制对应信息，此时点击 OK 允许重启即可。
图 21
运行应用程序：运行目标应用，执行相关被怀疑引入内存泄露的业务操作，持续一段时间以增加内存压力和捕获更多数据。
停止录制：自动触发抓取一份 Snapshot 快照用于关联分析。点击快照，查找到疑似泄漏对象 Proxy 。
图 22
泄漏对象关联分析
定位可疑 ArkTS 对象：选中一个怀疑被泄漏的 ArkTS 对象实例（或对象类型），查看扩展标签页。
图 23
查看 Native List：若某个 ArkTS 对象的 distance 值为 1，则可以通过扩展标签页中的 Native List 标签页，查看所有当前与该 JS 对象关联的 Native 句柄引用，以确认该 JS 对象是被 Local Handle 或 Global Handle 引用的对象。
图 24
关键信息：
句柄类型：调用栈底层的符号 ArkGlobalHandle 或 ArkLocalHandle 判断泄漏类型
调用栈：通过调用栈，可以定位到应用的 Native 代码（可能是 ArkUI 框架代码或你自己代码）中创建 napi_ref 的地方。
注意点：
如果该 JS 对象节点不是一个被 Local Handle 或者 Global Handle 引用的对象，则会提示 "No Detail"；
如果该 JS 对象确实是一个被 Local Handle 或者 Global Handle 引用的对象，但是对应的 native 内存的申请事件已经在此次录制之前完成内存分配，本次录制结果则无法展示对应的内存申请调用栈，需要重新录制，录制时需要注意将录制时执行的业务逻辑范围调整的尽量更早一些。
分析内存分配调用栈
排查调用栈：“Native List”标签页中的调用栈，找到对应业务代码
关键排查点：
检查是否在适当的时候调用了对应的句柄释放接口如 napi_delete_reference 等。
梳理这段 Native 代码需要引用 ArkTS 对象的合理性，识别这个引用的生命周期是否过长，是否应该在某个条件满足后被释放；
对于 napi_ref，其引用计数是关键。确保在不再需要引用时正确调用了 napi_delete_reference。注意，引用计数可能因其他代码路径的创建或删除操作而意外增减。
检查句柄的作用域是否合理。local handle 是否应该只在 JS 执行上下文切换前使用？global handle 是否真的需要在整个应用生命周期都有效 。
图 25
1.2.3 修复验证
重新运行应用，再次使用 Memory 泳道监控。
重复多次进出消息中心页。
验证结果：
内存曲线恢复锯齿状，每次退出后回落至基线。
再次抓取快照对比，多次操作后业务对象实例数量无明显增长。
泄漏问题已修复。
图 26
图 27
1.3 附录 1 ArkTS 泄漏根因
ArkTS 运行时采用分代回收模型 ，将对象按生命周期划分为新生代和老年代。使用标记-清除（mark-and-sweep）算法回收内存，所有可达对象被标记为存活，不可达对象则被回收。每次 GC 都是从根节点开始遍历，因此根节点被称为 GC Root。该树的快照如图 28 所示。
图 28
理解 GC 的核心在于一个关键洞察：GC 只回收“无法从 GC Root 到达”的对象。只要你的对象还挂在那棵引用树上，哪怕你已经忘记它、不再需要它，GC 也无法回收。换句话说，内存泄漏的本质不是 GC 失效，而是开发者留下了不该留的引用链。因此排查内存泄漏的关键，就是找到那条从 GC Root 出发、让无用对象“存活”的引用路径，并在适当位置将其切断。
