文档开发者中心
我的
|

HarmonyOS 6

HarmonyOS 5

requireNapi 一直返回 undefined,nativeLibraryPath 显示 libs/arm64,但 HAP 实际打包到了 arm64-v8a

已解决

大佬们好,我在做 NAPI 模块开发,需要在 ArkTS 侧加载一个 C++ 编写的 so 库。

我的配置是这样的:module.json5 里设置了 nativeLibraryPath: "libs/arm64",compressNativeLibs=false,libIsolation=false。HAP 打包完之后,我用 zip 工具解压看了一下,so 文件实际被打包到了 libs/arm64-v8a/ 目录下。

然后在 ArkTS 侧调用 requireNapi('xxx'),始终返回 undefined。NAPI 模块里注册的构造函数日志完全没有出现。

我尝试过:

  • 在 oh-package.json5 里配置 nativeModule,指定 name 和 library;

  • C++ 侧 napi_module.nm_modname 也设置成了对应的模块名;

  • ArkTS 侧试了各种传入参数组合:模块名、带 lib 前缀的 so 文件名、'entry' 等各种写法。

但都不管用。

更诡异的是,我想把 abiFilters 改成 arm64 来匹配 nativeLibraryPath 的路径,结果 hvigor 直接报错说不支持,allowedValues 里只有 'arm64-v8a'、'armeabi-v7a'、'x86_64' 这三个选项。

想请教几个问题:

  1. HarmonyOS NEXT 的 nativeLibraryPath 显示 libs/arm64 是正常的吗? 如果系统只认 arm64-v8a 这个 ABI 名称,那 module.json5 里配置 libs/arm64 是不是根本就不会被正确解析?

  2. requireNapi 查找 so 库的逻辑到底是什么? 是严格按照 nativeLibraryPath 配置的路径去找,还是会根据设备的 ABI 自动做路径映射?如果会映射,那映射规则是什么?

  3. 有没有官方推荐的 Native 模块注册方式或配置项,可以强制让 requireNapi 正确找到 so 库? 是在 module.json5、app.json5 还是 oh-package.json5 里配置?

  4. 我注意到 bm dump 命令看到的 nativeLibraryPath 和 HAP 实际打包路径不一致,这是不是说明问题出在构建阶段,hvigor 打包时没有把 nativeLibraryPath 的配置正确传递到最终的 HAP manifest 里?

  5. MUSL-LDSO 的依赖错误日志也没有出现,所以应该不是 so 库本身有缺失依赖的问题。如果路径配置都对,还有什么原因会导致 requireNapi 返回 undefined?

这个问题卡了我好几天了,网上关于 NAPI 模块加载的帖子也不多,大部分都是讲怎么注册的,很少有讲这种路径不匹配导致加载失败的坑。希望有经验的大佬指点一下,谢谢!

点赞
收藏
回复
5
分享
举报
浏览133 发布于2026-08-27 02:10天津
全部评论
最多点赞
最新发布
最早发布
|
采纳答复

结论:libs/arm64-v8a/ 是正常且受 Hvigor 支持的 ABI 目录,不能把 abiFilters 改成 arm64。应用内自定义 Node-API 模块不要把 requireNapi() 当作按路径 dlopen 的接口;官方示例的稳定加载方式是让构建系统打包 libxxx.so,再在 ArkTS 中静态 import xxx from 'libxxx.so'。bm dump 显示的 nativeLibraryPath 与 HAP 内部 ABI 子目录文本不同,本身不足以证明构建传递错误。

先把最小工程的命名统一:CMake target 为 entry,产物为 libentry.so,nm_modname 为 entry,ArkTS 导入名为 libentry.so。nm_modname 区分大小写,应与 so 模块名(去掉 lib 前缀和 .so 后缀)一致。

构建配置继续使用 Hvigor 允许的 ABI 名称 arm64-v8a。建议按以下顺序排查:

1. 删除模块 build、.cxx 等缓存后重建;解压 HAP,确认 libs/arm64-v8a/libentry.so 确实存在,不要为匹配 dump 文本改成非法 arm64。

2. 检查 add_library(entry ...)、libentry.so、nm_modname="entry"、类型包 name="libentry.so"、ArkTS import 'libentry.so' 五处大小写完全一致。

3. 确认注册入口未被条件编译移除;Init 声明 static,每个 so 只注册一个 napi_module,避免多个 so 的构造函数名重复。

4. 如果 so 曾被业务代码提前 dlopen,不要依赖普通 constructor 重复注册;按官方规范导出 napi_onLoad,在其中调用 napi_module_register,再由 ArkTS import 触发加载。

5. 清缓存后仍失败,再查动态依赖日志,重点检索 MUSL-LDSO、dlopen、symbol not found,并确认所有依赖 so 都打进相同 ABI 目录。constructor 日志完全没有出现,更像导入方式或模块名没有命中,或者 so 根本未被加载。

所以 nativeLibraryPath: libs/arm64 不应作为应用侧强制加载自定义 so 的控制手段,也无需在 app.json5 额外制造映射。先用官方 import 'libentry.so' 链路跑通最小 ping(),再逐步加回业务依赖;若最小工程可用而原工程不可用,差异通常在模块命名、重复注册、提前 dlopen 或依赖库。

官方资料:

Node-API 开发规范:https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/napi-guidelines

扩展 Node-API 示例:https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/use-napi-about-extension-V5

Hvigor abiFilters 配置:https://developer.huawei.com/consumer/cn/doc/harmonyos-center-guides/faqs-compiling-and-building-91-0000001971846869

C++ 最小注册示例:

收起
自动换行
深色代码主题
复制
#include "napi/native_api.h"

static napi_value Ping(napi_env env, napi_callback_info info)
{
    napi_value result = nullptr;
    napi_create_string_utf8(env, "pong", NAPI_AUTO_LENGTH, &result);
    return result;
}

EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports)
{
    napi_property_descriptor desc[] = {
        { "ping", nullptr, Ping, nullptr, nullptr, nullptr, napi_default, nullptr }
    };
    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
    return exports;
}
EXTERN_C_END

static napi_module entryModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init,
    .nm_modname = "entry",
    .nm_priv = nullptr,
    .reserved = { 0 }
};

extern "C" __attribute__((constructor))
void RegisterEntryModule()
{
    napi_module_register(&entryModule);
}

ArkTS 加载示例:

收起
自动换行
深色代码主题
复制
import nativeEntry from 'libentry.so'

const value: string = nativeEntry.ping()
console.info(`native ping=${value}`)
展开全部
4楼回复于2026-08-27 05:16 来自湖北

libs/arm64 与 HAP 内的 libs/arm64-v8a 属于运行态路径和打包 ABI 目录两套命名,看到不一致本身正常,不能据此判断构建失败。abiFilters 应保持 arm64-v8a,不要改成 arm64。

  • 应用自建 NAPI 模块的官方加载方式是:

    收起
    自动换行
    深色代码主题
    复制
    import nativeModule from 'libxxx.so'

    不建议用 requireNapi('xxx') 验证它;该调用返回 undefined 时,优先改为上述静态导入排查。

  • 名称必须严格对应:CMake 产物 libxxx.so → nm_modname = "xxx" → ArkTS import ... from 'libxxx.so'。大小写也必须一致,nm_modname 不带 lib 和 .so。

  • 不需要靠 oh-package.json5 的 nativeModule 或手改 nativeLibraryPath 强制定位;本地 NAPI 是否被打入 HAP,主要由 externalNativeOptions.abiFilters、CMake target 和依赖链接决定。

  • bm dump 的 nativeLibraryPath: libs/arm64 是安装后的库搜索位置描述;ZIP 内使用 arm64-v8a 是标准 ABI 打包目录,两者不要求字面一致。

  • 若改成 import 仍加载失败,再查:libxxx.so 是否在目标 ABI 目录、构造函数是否实际链接进最终 so、target_link_libraries 的三方依赖是否齐全,以及 hilog 中的 NAPI/dlopen 错误。没有日志不代表依赖一定没问题。

官方资料:

展开全部
1楼编辑于2026-08-27 02:55 来自广东
先确认 HAP 内的真实目录、库名和 ABI,再按打包后的目录配置 nativeLibraryPath;不要把 Android 的 arm64-v8a 路径名直接套到鸿蒙配置。用解压结果和 hdc shell 的实际路径对照,检查 so 依赖是否齐全、架构是否匹配,改配置后要 clean 后重新打包。 
5楼回复于2026-08-27 14:33 来自四川
  1. 删掉 module.json5 中所有关于 nativeLibraryPath 的手动篡改,恢复默认,让系统和构建工具自己处理。
  2. 确保在模块的 build-profile.json5 中,abiFilters 声明为标准的 ["arm64-v8a"]。
  3. 检查 C++ 编译出来的动态库文件名,必须是全小写的 libxxx.so 格式。
  4. 重构 oh-package.json5 中的 nativeModule,并改用 import xxx from 'libxxx.so' 语法引入。
  5. 执行一次 Build -> Clean Project:Hvigor 经常会缓存旧的打包路径,修改了配置文件后,必须 Clean 才会重新生成最终的清单文件。
3楼回复于2026-08-27 03:08 来自重庆

路径不匹配基本就是根因:module.json5 的 nativeLibraryPath 配置的目录名要和 HAP 实际打包目录一致,而系统/工具链认的是 ABI 标准名 arm64-v8a,你配 libs/arm64 而实际打包到 libs/arm64-v8a,requireNapi 按配置路径找自然找不到。abiFilters 只有 arm64-v8a/armeabi-v7a/x86_64 三个合法值,hvigor 报错是正常的。

改法:把 module.json5 里的 nativeLibraryPath 直接写成 libs/arm64-v8a(或更常规的做法是不配 nativeLibraryPath,把 so 放在默认的 libs/arm64-v8a 目录,由构建自动处理):

收起
自动换行
深色代码主题
复制
{
  "module": {
    "nativeLibraryPath": "libs/arm64-v8a",
    "compressNativeLibs": false,
    "libIsolation": false
  }
}

requireNapi 的查找顺序:先按 nativeLibraryPath 定位目录,再按模块名/文件名匹配 so,最后按设备 ABI 子目录查找;路径对不上、模块名不一致、nm_modname 与 requireNapi 参数不一致都会 undefined。如果改完还不行,用 bm dump 看 HAP manifest 里实际写入的 nativeLibraryPath 是否和你配置一致,并确认 so 依赖的 MUSL 符号没有缺失(可用 ldd 检查)。

 

2楼回复于2026-08-27 03:05 来自四川
写回答
新增插入模板功能
一键使用模板,快速填写内容,轻松发帖~
知道了
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。

我要提问题

了解社区公约,与您携手共创和谐专业的开发者社区。