HarmonyOS NAPI实战避坑：如何避免 napi_value 悬挂指针问题

HarmonyOS社区小助手

73人浏览 · 2026-07-31 16:04:16

HarmonyOS社区小助手 · 2026-07-31 16:04:16 发布

本原创文章帖发布在华为开发者联盟社区，欢迎开发者前往访问评论交流，更多与该内容相关讨论，请点击原帖查看：

HarmonyOS NAPI实战避坑：如何避免 napi_value 悬挂指针问题-华为开发者话题 | 华为开发者联盟

在鸿蒙应用开发中，不知道你有没有遇到过这种“灵异事件”：

明明刚才还活蹦乱跳的JS对象，转眼间就“人间蒸发”了。你的代码只是轻轻摸了一下它的属性，应用就“啪”地一声，崩溃了。

日志里抛出一行冷冰冰的异常：

ReferenceError: Can not get Prototype on non ECMA Object

翻译成人话就是：“我拿到的这个东西，根本就不是个正经的JS对象，连原型都没有，你让我怎么操作？”

如果你曾为此抓耳挠腮，别急。今天我们就来揭开这个错误背后的“真凶”——悬空的napi_value句柄。它就像一个披着对象外衣的幽灵，看着像那么回事，一碰就碎。

一、根因：你把“临时工”当“正式工”用了

在HarmonyOS的NAPI交互中，napi_value是一个很特殊的角色。它本质上是一个局部句柄，类似于一个“临时工”工牌。它的有效生命周期，仅限于当前函数调用栈和HandleScope（作用域）之内。

一旦这个作用域结束（比如函数返回），或者垃圾回收（GC）被触发，这个“临时工”工牌就会被收回。如果你非要拿着这个过期的工牌去访问原本对应的JavaScript对象，引擎就会告诉你：“我不认识这个人。”

最常见的翻车姿势，就是把napi_value直接扔进Native层的全局变量里存着，想着下次再拿出来用。
这就好比你把临时工的门禁卡偷偷复制了一份，结果第二天门禁系统更新了，你拿着复制卡去刷——门没开，人被抓了。

二、案发现场：一次点击，两次崩溃

我们来看一个真实的“惨案”：

ArkTS侧代码很干净：

// 先添加一个数组
testNapi.add(2, 3);  
// 手动触发垃圾回收（模拟内存紧张）
ArkTools.hintGC();  
// 再获取那个数组的长度
const len = testNapi.getvalue().length;  // 💥 崩溃点

Native 侧（C++）是这么写的“有 Bug”的代码：

// 全局变量，赤裸裸地存了一个 napi_value
napi_value g_globalArray = nullptr;

napi_value Add(napi_env env, ...) {
    napi_value jsArray;
    napi_create_array(env, &jsArray);  // 建一个数组
    // ... 往数组里塞数据 ...
    g_globalArray = jsArray;  // ❌ 直接赋值给全局，危险！
    return someResult;
}

napi_value GetValue(napi_env env, ...) {
    return g_globalArray;  // ❌ 返回一个可能已死的句柄
}

崩溃过程还原：

1. 调用add时，在HandleScope内创建了一个数组jsArray，并顺手把它赋给了全局变量g_globalArray。

2. 函数结束，HandleScope关闭，jsArray的引用计数减少，它变成了“可被回收”的状态。

3. 紧接着ArkTS侧调用ArkTools.hintGC()，垃圾回收器启动，那个数组对象被物理回收，内存被释放。

4. 但g_globalArray还傻傻地保存着原来那块内存的地址——现在它成了一个悬空指针。

5. 最后调用GetValue返回这个地址，并在ArkTS侧访问.length。引擎一看，这块内存里根本不是ECMA对象，于是怒抛Can not get Prototype on non ECMA Object。

三、破案神器：把“临时工”转正

问题的核心就是：局部句柄不能直接长期持有。正确的做法是，给它办一张“正式工”工牌——也就是 napi_ref（持久引用）。

修复方案非常简单，把全局变量类型改成napi_ref，并在创建对象后立即创建引用：

// 全局变量改为 napi_ref 类型
napi_ref g_globalArrayRef = nullptr;

// 创建对象时
napi_value jsArray;
napi_create_array(env, &jsArray);
// 为 jsArray 创建持久引用，引用计数 +1，防止被 GC 回收
napi_create_reference(env, jsArray, 1, &g_globalArrayRef);

// 获取对象时
napi_value GetValue(napi_env env, ...) {
    napi_value result = nullptr;
    napi_get_reference_value(env, g_globalArrayRef, &result);
    return result;  // 安全返回
}

// 当确定不再需要时（如模块卸载），必须释放引用
// napi_delete_reference(env, g_globalArrayRef);

这样一来，只要napi_ref还在，垃圾回收器就不会动你的对象。你拿到的是一个活生生的JavaScript数组，访问.length自然稳稳当当。