进阶:NAPI 原生扩展与高性能互操作
本篇要点:能把一段 C/C++ 代码安全地接进 ArkTS,说清
napi_value为什么不能存、原生线程怎么往 JS 侧投递、崩溃栈怎么还原成行号,并在动手之前先算清这笔收益。 前置:《构建与发布:hvigor、多模块与上架》的 hvigor 构建与《性能优化:布局、长列表与帧率分析》的性能分析方法是这一章的地基。没读过也能跟上,但需要知道一个 HAP 是怎么被编出来的。
为什么需要它
2025 年底有一个导出模块遇到过这样的需求:用户勾选 3000 条记录导出成压缩包。ArkTS 侧压缩一段 4 MB 的 JSON 要 2.8 秒,主线程整个卡住,转圈动画停在第一帧。
第一版方案是把它挪进 TaskPool。挪完界面不卡了,耗时一点没变——计算量本来就在那儿。第二版才决定用 C++:项目里躺着一份现成的 zlib 封装,用 ArkTS 重写一遍没有任何意义。于是引入 NAPI。
NAPI(Native API)是 ArkTS 与 C/C++ 之间的接口层,形式是一组 napi_* 函数。代码编过、跑通、单测全绿。然后它开始在切后台再回来的时候崩,测试同事连着点了二十几次,崩一次,栈浅到看不出是哪一行。
排查里最容易走错的一步,是把它当内存越界查。它其实是生命周期问题:ArkTS 侧的 napi_env 跟 Ability 绑定,页面销毁、Ability 重建之后,native 侧持有的东西就成了悬空指针。所以这一章的顺序是先讲清"谁拥有这块内存",再讲怎么快,最后讲崩了怎么查。
截至 2026 年 11 月,本篇事实基线取 HarmonyOS 6.1.x(API 23/24)与配套 NDK,napi_* 接口在 6.x 上保持稳定;个别接口的引入版本以 HarmonyOS 开发者文档中心 Native API 分区的标注为准。那一栏分华为侧与 OpenHarmony 侧两套文档,函数签名与回调时序有细微差别,不要互相替代。
核心概念
句柄与作用域:napi_value 不是对象
napi_env 是当前 ArkTS 运行时的上下文句柄,一个 Ability 对应一个,Ability 重建就换一个。napi_value 是某个 JS 值的句柄,它挂在当前的 napi_handle_scope 上,回调函数一返回,作用域关闭,这批句柄集体失效。
类比:napi_value 像图书馆的索书号,不是书本身。索书号只在本次借阅登记(handle scope)内有效,登记注销之后号还在你手里,但书架已经换了。
反例:把回调参数里的 napi_value 存进全局 std::map,想着"下次用的时候再取"。在 Node 插件里这么写多数时候能跑,在这里足够崩。要跨回调保存,只有一条路——napi_create_reference 建强引用,用完 napi_delete_reference。
绑定原生对象则用 napi_wrap,把 C++ 对象的指针挂到某个 JS 对象上,并在 napi_finalize 回调里释放。这样 JS 对象被回收时,原生资源跟着走,生命周期自动对齐。这也是为什么代码评审的第一条该是:搜一遍 static 和全局变量,凡是存了 napi_env 或 napi_value 的,全部改掉。
崩溃形态如图 11-1 所示。
图 11-1 三种持有方式对应的三种结局
注意图 11-1 里那个分支判断的位置:决定崩不崩的不是线程数,也不是编译器优化等级,而是你把句柄存到了哪里。
线程模型:一次性任务与持续推送
把重活挪出 JS 线程有两条路,选错的代价很高。区别不在"能不能后台跑",在投递语义。
| 机制 | 适用场景 | 语义与限制 |
|---|---|---|
napi_create_async_work | 一次性后台任务,做完回调一次 | 回调仍在 JS 线程执行;做不了流式进度 |
napi_create_threadsafe_function | 原生线程持续向 JS 推送 | 队列"尽力投递",队列满时按策略丢弃或阻塞 |
| TaskPool / Worker(《ArkTS 语言基础:从 TypeScript 到 ArkTS》) | 纯 ArkTS 的并发 | 跨不了语言边界,但调试成本低得多 |
选 threadsafe function(线程安全函数)时,第三个参数决定了队列满的行为:napi_tsfn_nonblocking 直接丢弃,napi_tsfn_blocking 阻塞原生线程。用 nonblocking 做进度条没问题,把数据量拉到十万条压测时,进度会从 12% 直接跳到 87%,中间那些回调压根没执行——这是设计意图,不是 bug。需要保序、保送达的数据通道,得自己在原生侧排队加序号校验。
队列容量参数传 0 表示不限制。不限制的意思是原生线程推多快,内存就涨多快,生产环境建议给一个有限值。
内存归属:ArrayBuffer 的指针归谁
napi_get_arraybuffer_info 拿到的那个 void* 归 JS 引擎所有,只在本次调用内有效。想在工作线程里异步使用它,只有两种做法:当场 memcpy 出来自己管,或者反过来用 napi_create_external_arraybuffer,把你分配的内存交给引擎接管,让它在 GC 时替你释放。
反例:边收数据边解析的模块里,把这个指针直接丢给工作线程。GC 一回收,读到的就是随机内容,崩得非常随机。
还有一处容易忘的上报:napi_adjust_external_memory。native 侧自己 malloc 的大块内存,如果不告诉引擎,GC 对真实内存压力没有感知,表现是"native 内存一路涨,JS 堆却很小"。这个函数的收益很难量化,但至少在内存告警复现时可以把它当成一个变量排除掉。
构建:nm_modname 是个字符串
NAPI 模块通过 napi_module_register 注册,产物是一个 .so,放在 entry/src/main/cpp 下由 CMake 编译。真正容易出错的不是 CMake 语法,是名字对齐:nm_modname 必须等于 ArkTS 侧 import 语句里去掉 lib 前缀与 .so 后缀的那一段。
写 nm_modname = "entry",就要 import entry from 'libentry.so'。不一致的表现是 ArkTS 侧报模块不存在,不指向任何一行 C++,也没有提示说"名字拼错了"。
动手实践
四步,每步都能自己验证。前提:DevEco Studio 已装 NDK,工程里至少有一个 entry 模块。
第一步,让 CMake 参与构建。 新建 entry/src/main/cpp/CMakeLists.txt:
cmake_minimum_required(VERSION 3.5.0)
project(entry)
set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR})
include_directories(${NATIVERENDER_ROOT_PATH})
add_library(entry SHARED napi_init.cpp)
target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so)运行结果:此时 hvigorw assembleHap 依然通过,但 entry/build/default/intermediates/libs/ 是空的——文件放在目录里不等于参与了构建,还要下一步那行配置。
然后在模块级 build-profile.json5 里挂上它:
"buildOption": {
"externalNativeOptions": {
"path": "./src/main/cpp/CMakeLists.txt",
"cppFlags": "-g -O2 -fno-omit-frame-pointer",
"abiFilters": ["arm64-v8a", "x86_64"]
}
}运行结果:先 hvigorw --sync 同步一次,entry/.cxx/ 下出现 arm64-v8a 与 x86_64 两个子目录;再执行 hvigorw assembleHap --mode module -p product=default,entry/build/default/intermediates/libs/ 下出现 arm64-v8a/libentry.so 与 x86_64/libentry.so。少了 x86_64,模拟器上会报 dlopen failed: library "libentry.so" not found。
-fno-omit-frame-pointer 这行别省。它直接影响崩溃时能否还原调用链,比 -O2 省下来的那点收益值钱得多。
第二步,写最小可用的 native 模块。
// entry/src/main/cpp/napi_init.cpp
#include <napi/native_api.h>
#include <hilog/log.h>
#define LOG_TAG "NAPI_DEMO"
static napi_value Add(napi_env env, napi_callback_info info) {
size_t argc = 2;
napi_value args[2] = {nullptr};
napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
double a = 0, b = 0;
napi_get_value_double(env, args[0], &a);
napi_get_value_double(env, args[1], &b);
// %{public}s 才不会被脱敏成 <private>
OH_LOG_Print(LOG_TAG, LOG_INFO, 0x0001, "Add", "a=%{public}f b=%{public}f", a, b);
napi_value sum = nullptr;
napi_create_double(env, a + b, &sum);
return sum;
}
static napi_value Init(napi_env env, napi_value exports) {
napi_property_descriptor desc[] = {
{"add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr},
};
napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
return exports;
}
static napi_module demoModule = {
.nm_version = 1,
.nm_flags = 0,
.nm_filename = nullptr,
.nm_register_func = Init,
.nm_modname = "entry", // 对应 import 的 'libentry.so'
.nm_priv = nullptr,
.reserved = {0},
};
extern "C" __attribute__((constructor)) void RegisterEntryModule(void) {
napi_module_register(&demoModule);
}运行结果:hvigorw assembleHap 编译通过且没有警告,arm64-v8a 下的 libentry.so 约 30 KB。想确认符号真的注册了,用 nm -D libentry.so | grep RegisterEntryModule,能看到一行 T RegisterEntryModule。名字写错在这一步不会报——要到 ArkTS 侧 import 时才暴露。
第三步,在 ArkTS 侧调它。 先在 entry/src/main/cpp/types/libentry/ 下放一份 Index.d.ts,内容一行:export const add: (a: number, b: number) => number;,再让 oh-package.json5 的 types 指向它。少了这一步,ArkTS 编译器会报 Cannot find module 'libentry.so'。
// entry/src/main/ets/pages/Index.ets
import native from 'libentry.so';
import { hilog } from '@kit.PerformanceAnalysisKit';
@Entry
@Component
struct Index {
@State result: number = 0;
build() {
Column({ space: 16 }) {
Text(`add(1.5, 2.5) = ${this.result}`).fontSize(20)
Button('调用 native').onClick(() => {
this.result = native.add(1.5, 2.5);
hilog.info(0x0001, 'NAPI_DEMO', 'result=%{public}d', this.result);
})
}.width('100%').padding(24)
}
}运行结果:点击按钮后页面显示 add(1.5, 2.5) = 4,DevEco 的 Log 窗口过滤 NAPI_DEMO 能看到两行——Add: a=1.500000 b=2.500000 和 result=4。如果只看到 a=<private> b=<private>,说明 OH_LOG_Print 里用了 %s,被脱敏了。
第四步,把崩溃变成行号。 release 包把 so strip 之后,崩溃栈里只剩地址,需要靠符号表反解:
# 1) 实时过滤自己模块的日志
hdc shell hilog | grep NAPI_DEMO
# 2) 拉 cppcrash 日志(路径以设备实际为准)
hdc file recv /data/log/faultlog/faultlogger/ ./faultlog/
# 3) 反解地址:so 必须是崩溃时加载的那一份
${NDK_PATH}/llvm/bin/addr2line -C -f -e libentry.so 0x1a2c运行结果:addr2line 打印出函数名与 napi_init.cpp:23 这样的位置。如果给出的行号落在注释或空行上,八成是符号表与二进制不是同一次构建——拿另一天产物去解,会得到一个看起来合理、实际完全错误的行号。所以流水线里除发布包之外,要按构建号额外归档一份带符号的 so。
排查时还有一个反直觉的细节:崩溃日志的栈顶常常是 libc.so 而不是 libentry.so,看着像系统问题,实际是你的 napi_value 悬空后触发了引擎内部的空指针解引用。只看栈顶那一帧方向必然跑偏,往下翻两三帧,看是不是又回到自己的 so。
常见误解
"NAPI 就是 Node 的 N-API 换了个名字,插件可以直接搬。" 语法确实几乎一致,napi_get_cb_info、napi_create_string_utf8、napi_define_properties 都能照抄。但宿主环境不同:Node 插件大多跑在单进程、单线程、生命周期由进程兜底的环境里,env 基本不变;鸿蒙这边 env 跟 Ability 走,Ability 重建就换一个。照搬的代码能编过、能跑通,然后在某个销毁时序上崩。
"崩溃基本都是参数没校验,加个判空就好了。" 参数校验漏了是必崩,好查,日志里一次就复现;悬空句柄是偶发崩,二十几次一次,才要命。这两类问题在栈上长得完全不一样,前者指向你的函数入口,后者指向引擎内部。
"上了 NAPI 就会快。" 收益来自"一次跨界干很多活",不是"把同样的活换个语言写"。把 add(a, b) 搬到 native,除了证明能编译通过,没有性能意义;业务逻辑、状态管理、网络请求、JSON 解析这四类留在 ArkTS 侧,调试成本低一半,收益接近零。加解密、编解码、复用已有 C/C++ 库,这些值得。每帧调用几十次、每次传一百字节的高频小数据,先重构调用粒度往往比换语言更有效——把"每帧 60 次、每次 100 字节"改成"每帧 1 次、一次传一帧",收益经常比上 NAPI 还大。
小结
napi_env与napi_value都是句柄:env 与 Ability 同生共死,value 与 handle scope 同生共死。跨回调保存只能靠napi_create_reference。- 原生对象用
napi_wrap挂到 JS 对象上,在napi_finalize里释放;全局变量和static是这类 bug 的主要来源。 - 一次性任务用
async_work,原生线程持续推送用 threadsafe function;nonblocking会丢消息,不保序也不保送达,队列容量给 0 等于不限内存。 napi_get_arraybuffer_info的指针只在本次调用有效,异步使用必须先memcpy或改用napi_create_external_arraybuffer。- 崩溃定位依赖三件事:带符号的 so、同一次构建、正确的
addr2line;日志里的%{public}s与nm_modname是两条最容易漏的字符串。 - 性能结论必须来自对照实验:固定输入与设备、先写逻辑等价的 ArkTS 版、预热后取中位数、把耗时拆成数据准备、纯计算、回传三段。多数"NAPI 没变快"的案例,是类型转换占了七成。
相关主题
能写 native 扩展,说明这一门课里最难的一部分已经过去了。但还有一类应用根本不需要"安装"——卡片点开即用、用完即走。《进阶:元服务与免安装体验》讲 元服务与免安装体验:它的包结构比 HAP 严格得多,体积、启动、分发都有额外约束,而《构建与发布:hvigor、多模块与上架》学的模块拆分和《权限与隐私合规:上架审核要点》的权限最小化,在那一章会同时被检验一次。