Node-API简介
==========

#### 场景介绍

HarmonyOS Node-API是基于Node.js 18.x LTS的[Node-API](https://nodejs.org/docs/latest-v12.x/api/n-api.html)规范扩展开发的机制，为开发者提供了ArkTS/JS与C/C++模块之间的交互能力。它提供了一组稳定的、跨平台的API，可以在不同的操作系统上使用。

本文中如无特别说明，后续均使用Node-API指代HarmonyOS Node-API能力。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/a4/v3/HDnIKnbUS8W_kATmRt-pqg/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073806Z&HW-CC-Expire=86400&HW-CC-Sign=5A80A42F20250E77B9FA534A1EE9DBD5FB4DEAA35AE314486E557F153812D752)

HarmonyOS Node-API与Node.js 18.x LTS的Node-API规范的接口异同点，详见[Node-API参考文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/napi)

一般情况下HarmonyOS应用开发使用ArkTS/JS语言，但部分场景由于性能、效率等要求，比如游戏、物理模拟等，需要依赖使用现有的C/C++库。Node-API规范封装了I/O、CPU密集型、OS底层等能力并对外暴露C接口，使用C/C++模块的注册机制，向ArkTS/JS对象上挂载属性和方法的方式来实现ArkTS/JS和C/C++的交互。主要场景如下：

*   系统可以将框架层丰富的模块功能通过Node-API的模块注册机制对外暴露ArkTS/JS的接口，将C/C++的能力开放给应用的ArkTS/JS层。
    
*   应用开发者也可以选择将一些对性能、底层系统调用有要求的核心功能用C/C++封装实现，再通过ArkTS/JS接口使用，提高应用本身的执行效率。
    

#### Node-API的组成架构

**图1** Node-API的组成架构

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/2c/v3/xQ1gnbwqQxerXxZHEBw5ew/zh-cn_image_0000002625109193.png?HW-CC-KV=V1&HW-CC-Date=20260612T073806Z&HW-CC-Expire=86400&HW-CC-Sign=327EFE4C2BF171B539FE449B27D03EC9D2C5A5049A8109BD730E4A63CD991022)

*   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的关键交互流程

**图2** Node-API的关键交互流程

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/0e/v3/HQJTnc0mScmi7AaqwQTt8A/zh-cn_image_0000002594669676.png?HW-CC-KV=V1&HW-CC-Date=20260612T073806Z&HW-CC-Expire=86400&HW-CC-Sign=A6F5FC8DF498E84CDB7628931EF2C9BDD359ACE038EEED5387E245187A01CAC5)

ArkTS和C++之间的交互流程，主要分为以下两步：

1.  **初始化阶段**：当ArkTS侧在import一个Native模块时，ArkTS引擎会调用ModuleManager加载模块对应的so及其依赖。首次加载时会触发模块的注册，将模块定义的方法属性挂载到exports对象上并返回该对象。
    
2.  **调用阶段**：当ArkTS侧通过上述import返回的对象调用方法时，ArkTS引擎会找到并调用对应的C/C++方法。