一、Node-API
HarmonyOS Node-API是基于Node.js 18.x LTS的Node-API规范扩展开发的机制，提供了ArkTS/JS与C/C++模块之间的交互能力。它提供了一组稳定的、跨平台的API，可以在不同的操作系统上使用。
适用场景
| 系统框架层 | 将框架层丰富的模块功能通过Node-API的模块注册机制对外暴露ArkTS/JS接口，将C/C++能力开放给应用的ArkTS/JS层 |
| 应用开发层 | 将性能敏感、对底层系统调用有要求的核心功能用C/C++封装实现，再通过ArkTS/JS接口使用，提高应用本身的执行效率 |
Node-API规范封装了I/O、CPU密集型、OS底层等能力并对外暴露C接口，使用C/C++模块的注册机制，向ArkTS/JS对象上挂载属性和方法的方式来实现ArkTS/JS和C/C++的交互。
二、Node-API的组成架构
Node-API的组成架构主要包括以下组件：
| Native Module | 使用Node-API开发的模块，用于在ArkTS侧导入使用 |
| Node-API | 实现ArkTS与C/C++交互的逻辑 |
| ModuleManager | Native模块管理，包括加载、查找等 |
| ScopeManager | 管理napi_value的生命周期 |
| ReferenceManager | 管理napi_ref的生命周期 |
| NativeEngine | ArkTS引擎抽象层，统一ArkTS引擎在Node-API层的接口行为 |
| ArkCompiler ArkTS Runtime | ArkTS运行时 |
三、Node-API的交互流程
ArkTS和C++之间的交互流程主要分为两步：
3.1 初始化阶段
当ArkTS侧在import一个Native模块时：
ArkTS引擎调用ModuleManager加载模块对应的SO及其依赖
首次加载时触发模块的注册
将模块定义的方法属性挂载到exports对象上
返回该对象
3.2 调用阶段
当ArkTS侧通过上述import返回的对象调用方法时：
ArkTS引擎会找到并调用对应的C/C++方法。
3.3 流程示意图
ArkTS侧 import Native模块
↓
ModuleManager加载so及依赖
↓
首次加载触发模块注册
↓
方法属性挂载到exports对象
↓
ArkTS侧调用方法
↓
ArkTS引擎找到并调用对应C/C++方法
四、核心点
| Node-API定位 | 实现ArkTS/JS与C/C++交互的跨平台稳定API |
| 基于标准 | Node.js 18.x LTS的Node-API规范扩展 |
| 使用场景 | 系统框架层暴露C/C++能力，应用层实现性能敏感功能 |
| 关键流程 | 初始化阶段（import → 加载so → 注册 → 挂载exports）→ 调用阶段（调用方法 → 执行C/C++函数） |
4.2 关键组件
| Native Module | 开发的Node-API模块 |
| ModuleManager | 加载、查找Native模块 |
| ScopeManager | 管理napi_value生命周期 |
| ReferenceManager | 管理napi_ref生命周期 |
| NativeEngine | ArkTS引擎抽象层 |
鸿蒙Node-API是基于Node.js 18.x LTS扩展的ArkTS/JS与C/C++交互机制，通过ModuleManager加载so并注册模块，将方法挂载到exports对象供ArkTS侧调用，适用于系统框架层暴露C/C++能力和应用层实现性能敏感功能两大场景。
