Node-API

稳定性: 2 - 稳定的

¥Stability: 2 - Stable

Node-API（以前称为 N-API）是用于构建原生插件的 API。它独立于底层 JavaScript 运行时（例如 V8），并作为 Node.js 本身的一部分进行维护。此 API 将在 Node.js 的各个版本中保持稳定的应用二进制接口 (ABI)。它旨在将插件与底层 JavaScript 引擎的变化隔离开来，并允许为一个主要版本编译的模块无需重新编译即可在以后的 Node.js 主要版本上运行。ABI 稳定性 指南提供了更深入的解释。

¥Node-API (formerly N-API) is an API for building native Addons. It is independent from the underlying JavaScript runtime (for example, V8) and is maintained as part of Node.js itself. This API will be Application Binary Interface (ABI) stable across versions of Node.js. It is intended to insulate addons from changes in the underlying JavaScript engine and allow modules compiled for one major version to run on later major versions of Node.js without recompilation. The ABI Stability guide provides a more in-depth explanation.

插件是使用标头为 C++ 插件 的部分中概述的相同方法/工具构建/打包的。唯一的区别是原生代码使用的 API 集。不使用 V8 或 Node.js 的原生抽象 API，而是使用 Node-API 中可用的函数。

¥Addons are built/packaged with the same approach/tools outlined in the section titled C++ Addons. The only difference is the set of APIs that are used by the native code. Instead of using the V8 or Native Abstractions for Node.js APIs, the functions available in Node-API are used.

Node-API 公开的 API 通常用于创建和操作 JavaScript 值。概念和操作通常映射到 ECMA-262 语言规范中指定的想法。API 具有以下属性：

¥APIs exposed by Node-API are generally used to create and manipulate JavaScript values. Concepts and operations generally map to ideas specified in the ECMA-262 Language Specification. The APIs have the following properties:

  • 所有 Node-API 调用都会返回 napi_status 类型的状态代码。此状态指示 API 调用是成功还是失败。

    ¥All Node-API calls return a status code of type napi_status. This status indicates whether the API call succeeded or failed.

  • API 的返回值通过 out 参数传递。

    ¥The API's return value is passed via an out parameter.

  • 所有 JavaScript 值都被抽象为一个名为 napi_value 的不透明类型。

    ¥All JavaScript values are abstracted behind an opaque type named napi_value.

  • 如果出现错误状态代码，可以使用 napi_get_last_error_info 获取附加信息。可以在错误处理部分 错误处理 中找到更多信息。

    ¥In case of an error status code, additional information can be obtained using napi_get_last_error_info. More information can be found in the error handling section Error handling.