HarmonyOS Next开发学习手册——Node-API常见问题

ArkTS/JS侧import xxx from libxxx.so后，使用xxx报错显示undefined/not callable或明确的Error message

1. 排查.cpp文件在注册模块时的模块名称与so的名称匹配一致。

如模块名为entry，则so的名字为libentry.so，napi_module中nm_modname字段应为entry，大小写与模块名保持一致。

2.排查so是否加载成功。

应用启动时过滤模块加载相关日志，重点搜索"dlopen"关键字，确认是否有相关报错信息；常见加载失败原因有权限不足、so文件不存在以及so已拉入黑名单等，可根据以下关键错误日志确认问题。其中，多线程场景(worker、taskpool等)下优先检查模块实现中nm_modname是否与模块名一致，区分大小写。

3.排查依赖的so是否加载成功。

确定所依赖的其它so是否打包到应用中以及是否有权限打开。常见加载失败原因有权限不足、so文件不存在等，可根据以下关键错误日志确认问题。

4.排查模块导入方式与so路径是否对应。

若JS侧导入模块的形式为： import xxx from ‘@ohos.yyy.zzz’，则该so将在/system/lib/module/yyy中找libzzz.z.so或libzzz_napi.z.so，若so不存在或名称无法对应，则报错日志中会出现dlopen相关日志。

注意，32位系统路径为/system/lib，64位系统路径为/system/lib64。

已知关键错误日志	修改建议
module $SO is not allowed to load in restricted runtime	$SO表示模块名。该模块不在受限worker线程的so加载白名单，不允许加载，建议用户删除该模块。
module $SO is in blocklist, loading prohibited	$SO表示模块名。受卡片或者Extension管控，该模块在黑名单内，不允许加载，建议用户删除该模块。
load module failed. $ERRMSG	动态库加载失败。$ERRMSG表示加载失败原因，一般常见原因是so文件不存在、依赖的so文件不存在或者符号未定义，需根据加载失败原因具体分析。
try to load abc file from $FILEPATH failed.	通常加载动态库和abc文件为二选一：如果是要加载动态库并且加载失败，该告警可以忽略；如果是要加载abc文件，则该错误打印的原因是abc文件不存在，$FILEPATH表示模块路径。

1.如果有明确的Error message，可以通过Error message判断当前问题。

Error message	修改建议
First attempt: $ERRMSG	首先加载后缀不拼接’_napi’的模块名为’xxx’的so，如果加载失败会有该错误信息，$ERRMSG表示具体加载时的错误信息。
Second attempt: $ERRMSG	第二次加载后缀拼接’_napi’的模块名为’xxx_napi’的so，如果加载失败会有该错误信息，$ERRMSG表示具体加载时的错误信息。
try to load abc file from xxx failed	第三次加载名字为’xxx’的abc文件，如果加载失败会有该错误信息。
module xxx is not allowed to load in restricted runtime.	该模块不允许在受限运行时中使用，xxx表示模块名，建议用户删除该模块。
module xxx is in blocklist, loading prohibited.	该模块不允许在当前extension下使用，xxx表示模块名，建议用户删除该模块。

接口执行结果非预期，日志显示occur exception need return

部分Node-API接口在调用结束前会进行检查，检查虚拟机中是否存在JS异常。如果存在异常，则会打印出occur exception need return日志，并打印出检查点所在的行号，以及对应的Node-API接口名称。

解决此类问题有以下两种思路：

• 若该异常开发者不关心，可以选择直接清除。
  可直接使用napi接口napi_get_and_clear_last_exception，清理异常。调用时机：在打印occur exception need return日志的接口之前调用。

• 将该异常继续向上抛到ArkTS层，在ArkTS层进行捕获。
  发生异常时，可以选择走异常分支， 确保不再走多余的Native逻辑 ，直接返回到ArkTS层。

napi_value和napi_ref的生命周期有何区别

• native_value由HandleScope管理，一般开发者不需要自己加HandleScope（uv_queue_work的complete callback除外）。
• napi_ref由开发者自己管理，需要手动delete。

Node-API接口返回值不是napi_ok时，如何排查定位

Node-API接口正常执行后，会返回一个napi_ok的状态枚举值，若napi接口返回值不为napi_ok，可从以下几个方面进行排查。

• Node-API接口执行前一般会进行入参校验，首先进行的是判空校验。在代码中体现为：

CHECK_ENV： env判空校验
CHECK_ARG：其它入参判空校验

• 某些Node-API接口还有入参类型校验。比如napi_get_value_double接口是获取JS number对应的C double值，首先就要保证的是：JS value类型为number，因此可以看到相关校验。

RETURN_STATUS_IF_FALSE(env, nativeValue->TypeOf() == NATIVE_NUMBER, napi_number_expected);

• 还有一些接口会对其执行结果进行校验。比如napi_call_function这个接口，其功能是执行一个JS function，当JS function中出现异常时，Node-API将会返回napi_pending_exception的状态值。

auto resultValue = engine->CallFunction(nativeRecv, nativeFunc, nativeArgv, argc);
RETURN_STATUS_IF_FALSE(env, resultValue != nullptr, napi_pending_exception)

• 还有一些状态值需要根据相应Node-API接口具体分析：确认具体的状态值，分析这个状态值在什么情况下会返回，再排查具体出错原因。

鸿蒙全栈开发全新学习指南

之前总有很多小伙伴向我反馈说，不知道学习哪些鸿蒙开发技术？不知道需要重点掌握哪些鸿蒙应用开发知识点？而且学习时频繁踩坑，最终浪费大量时间。所以这里为大家准备了一份实用的鸿蒙（HarmonyOS NEXT）学习路线与学习文档用来跟着学习是非常有必要的。

针对一些列因素，整理了一套纯血版鸿蒙（HarmonyOS Next）全栈开发技术的学习路线，包含了鸿蒙开发必掌握的核心知识要点，内容有（ArkTS、ArkUI开发组件、Stage模型、多端部署、分布式应用开发、WebGL、元服务、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、OpenHarmony驱动开发、系统定制移植等等）鸿蒙（HarmonyOS NEXT）技术知识点。

本路线共分为四个阶段：

第一阶段：鸿蒙初中级开发必备技能

第二阶段：鸿蒙南北双向高工技能基础：gitee.com/MNxiaona/733GH

第三阶段：应用开发中高级就业技术

第四阶段：全网首发-工业级南向设备开发就业技术：gitee.com/MNxiaona/733GH

《鸿蒙 (Harmony OS)开发学习手册》（共计892页）

如何快速入门？

1.基本概念
2.构建第一个ArkTS应用
3.……

开发基础知识:gitee.com/MNxiaona/733GH

1.应用基础知识
2.配置文件
3.应用数据管理
4.应用安全管理
5.应用隐私保护
6.三方应用调用管控机制
7.资源分类与访问
8.学习ArkTS语言
9.……

基于ArkTS 开发

1.Ability开发
2.UI开发
3.公共事件与通知
4.窗口管理
5.媒体
6.安全
7.网络与链接
8.电话服务
9.数据管理
10.后台任务(Background Task)管理
11.设备管理
12.设备使用信息统计
13.DFX
14.国际化开发
15.折叠屏系列
16.……

鸿蒙开发面试真题（含参考答案）:gitee.com/MNxiaona/733GH

鸿蒙入门教学视频：

美团APP实战开发教学：gitee.com/MNxiaona/733GH

写在最后

• 如果你觉得这篇内容对你还蛮有帮助，我想邀请你帮我三个小忙：
• 点赞，转发，有你们的 『点赞和评论』，才是我创造的动力。
• 关注小编，同时可以期待后续文章ing🚀，不定期分享原创知识。
• 想要获取更多完整鸿蒙最新学习资源，请移步前往小编：gitee.com/MNxiaona/733GH