25.3 原生扩展开发：N-API 编写 C++ 扩展

Node.js 虽然功能强大，但终究是运行在单线程事件循环上的 JavaScript 运行时，面对 CPU 密集型计算、与操作系统底层交互或复用现有 C/C++ 库时，纯 JavaScript 往往会力不从心。Node.js 提供了原生扩展机制，允许开发者用 C/C++ 编写模块，直接编译为 .node 文件，由 JavaScript 调用，从而既保留 JavaScript 的灵活性，又获得接近底层的执行效率。

早年的原生扩展直接依赖 V8 和 libuv 的 API，编译出来的模块绑定到特定 Node.js 版本，升级时容易出错。N-API（现在官方命名为 Node-API）从 Node.js 8.0 开始引入，是一个稳定的 ABI 兼容层，它定义了一套与 JavaScript 引擎无关的 API，使得用 Node-API 编写的原生扩展可以在不同 Node.js 版本之间直接使用，无需重新编译。本节就以 N-API 为基础，带你从零实现一个 C++ 扩展，并讲清楚其中的关键概念和实用考量。

为什么需要原生扩展？

性能关键路径：例如图像处理、加密解密、大型数学运算，C++ 的速度远优于 JavaScript。
复用现有 C/C++ 库：企业已有的算法库、硬件驱动 SDK、通信协议解析往往只有 C/C++ 接口。
操作系统底层调用：某些系统调用或内核功能只能通过 C/C++ 高效调用。
内存和缓冲区精细控制：处理原始字节数据时，C++ 可以更直接地操作内存。

但请注意：引入 C++ 扩展会提高项目维护难度和构建复杂性，只有在确实必要时才使用。

N-API 的优势

ABI 稳定：扩展二进制文件不绑定 V8 版本，升级 Node.js 后无需重新编译，极大降低维护成本。
引擎无关：虽然当前 Node.js 使用 V8，但未来如果更换引擎，N-API 扩展仍然可以运行。
封装了复杂性：通过 N-API，你不需要直接操作 v8::Local、v8::Handle 等复杂对象，API 更加简洁和安全。
官方维护和支持：Node-API 和 node-addon-api（C++ 封装）由 Node.js 社区维护，长期支持。

目前推荐使用 node-addon-api，这是 N-API 的 C++ 包装器，提供了现代 C++ 风格（RAII、命名空间）和更好的类型安全。本节就基于 node-addon-api 来演示。

从零构建一个原生扩展

我们将实现一个简单的模块：提供一个 sum(a, b) 函数，计算两个数的和（虽然简单，但完整展示流程）。

1. 项目初始化

创建一个新的 Node.js 项目，并安装必要的构建工具。

mkdir native-demo && cd native-demo
npm init -y
npm install node-addon-api bindings

node-addon-api：C++ 头文件库，提供 N-API 的 C++ 接口。
bindings：一个帮助加载编译出的 .node 文件的实用库，避免写死路径。

2. 编写 C++ 代码

在项目根目录创建一个 src 目录，然后在其中创建 sum.cc。

// src/sum.cc
#include <napi.h>

// 实际业务逻辑：计算两数之和
Napi::Value Sum(const Napi::CallbackInfo& info) {
    Napi::Env env = info.Env();

    // 检查参数个数和类型，如果错误就抛异常
    if (info.Length() < 2) {
        Napi::TypeError::New(env, "需要两个参数").ThrowAsJavaScriptException();
        return env.Null();
    }
    if (!info[0].IsNumber() || !info[1].IsNumber()) {
        Napi::TypeError::New(env, "参数必须是数字").ThrowAsJavaScriptException();
        return env.Null();
    }

    double a = info[0].As<Napi::Number>().DoubleValue();
    double b = info[1].As<Napi::Number>().DoubleValue();
    double result = a + b;

    return Napi::Number::New(env, result);
}

// 初始化模块，导出 sum 函数
Napi::Object Init(Napi::Env env, Napi::Object exports) {
    exports.Set("sum", Napi::Function::New(env, Sum));
    return exports;
}

// NODE_API_MODULE 宏定义模块入口
NODE_API_MODULE(sum, Init)

解释：

Sum 函数接收一个 Napi::CallbackInfo 参数，它包含调用信息和传入的 JavaScript 参数。
从 info 中获取参数，进行类型校验，计算后返回 Napi::Number。
Init 函数将 Sum 绑定到模块导出对象的 sum 属性。
NODE_API_MODULE(sum, Init) 是注册入口的宏，注意第一个参数是模块名，必须与编译出的文件名一致。

3. 配置构建系统

为了让 Node.js 能够编译这个 C++ 文件，需要配置 binding.gyp 文件（GYP 格式），这是原生扩展的编译描述。

# binding.gyp
{
  "targets": [
    {
      "target_name": "sum",
      "sources": [ "src/sum.cc" ],
      "include_dirs": [
        "<!@(node -p \"require('node-addon-api').include\")"
      ],
      "dependencies": [
        "<!(node -p \"require('node-addon-api').gyp\")"
      ],
      "defines": [ "NAPI_DISABLE_CPP_EXCEPTIONS" ],
      "cflags!": [ "-fno-exceptions" ],
      "cflags_cc!": [ "-fno-exceptions" ]
    }
  ]
}

说明：

target_name：最终生成的 .node 文件名（不含扩展名），这里叫 sum。
sources：需要编译的源文件列表。
include_dirs 和 dependencies：通过命令行调用 node-addon-api 来获取正确的头文件路径和依赖，确保通用性。
cflags! 部分关闭了 -fno-exceptions，因为 node-addon-api 默认关闭了 C++ 异常，而我们希望保留异常处理以简化错误。

确保已安装 node-gyp 全局工具或作为开发依赖。

npm install -g node-gyp   # 或者 npx 执行

4. 编译扩展

node-gyp configure build

编译成功后会生成 build/Release/sum.node 文件。

5. 在 JavaScript 中调用

创建 index.js：

const sumAddon = require('bindings')('sum');

console.log(sumAddon.sum(3, 4));       // 7
console.log(sumAddon.sum(1.5, 2.5));   // 4

运行 node index.js，即可看到正确的输出。如果传入非法参数，会抛出 TypeError。

实用进阶：处理复杂数据类型

真实的扩展往往需要处理字符串、对象、Buffer、异步回调等。下面简要说明几种常见场景。

字符串操作

Napi::Value Greet(const Napi::CallbackInfo& info) {
    Napi::Env env = info.Env();
    std::string name = info[0].As<Napi::String>().Utf8Value();
    std::string greeting = "Hello, " + name;
    return Napi::String::New(env, greeting);
}

返回对象

Napi::Object CreateUser(const Napi::CallbackInfo& info) {
    Napi::Env env = info.Env();
    Napi::Object user = Napi::Object::New(env);
    user.Set("id", 1);
    user.Set("name", "Alice");
    return user;
}

处理 Buffer

void ProcessBuffer(const Napi::CallbackInfo& info) {
    Napi::Env env = info.Env();
    Napi::Buffer<char> buf = info[0].As<Napi::Buffer<char>>();
    char* data = buf.Data();
    size_t length = buf.Length();
    // 可对 data 进行读写
}

异步工作（避免阻塞事件循环）

如果 C++ 函数中有耗时操作（如复杂计算、文件 I/O），必须将其放入线程池异步执行，否则会阻塞 JavaScript 主线程。通过 Napi::AsyncWorker 可以方便实现。

#include <napi.h>
#include <thread>
#include <chrono>

class MyWorker : public Napi::AsyncWorker {
public:
    MyWorker(Napi::Function& callback, int input)
        : Napi::AsyncWorker(callback), input_(input), result_(0) {}

private:
    // 在线程池中执行耗时操作
    void Execute() override {
        // 模拟耗时计算
        std::this_thread::sleep_for(std::chrono::seconds(1));
        result_ = input_ * 2;
    }

    // 执行完毕后回调主线程
    void OnOK() override {
        Napi::Env env = Env();
        Callback().Call({Napi::Number::New(env, result_)});
    }

    int input_;
    int result_;
};

// 对外暴露的异步函数
Napi::Value AsyncMultiply(const Napi::CallbackInfo& info) {
    Napi::Env env = info.Env();
    int value = info[0].As<Napi::Number>().Int32Value();
    Napi::Function callback = info[1].As<Napi::Function>();

    MyWorker* worker = new MyWorker(callback, value);
    worker->Queue();
    return env.Undefined();
}

在 JavaScript 中调用：

addon.asyncMultiply(5, (result) => {
  console.log(result); // 10，约1秒后输出
});

编译与调试建议

跨平台注意：确保 binding.gyp 包含不同平台的编译选项，必要时配置条件编译。
错误处理：N-API 的异常不会自动抛出，需要显式调用 ThrowAsJavaScriptException。
调试：可以使用 C++ 调试器（gdb/lldb）附加到 Node.js 进程，或使用 ndb 等工具。编译时加上 --debug 标志生成调试符号。
预构建二进制：对于开源项目，可使用 prebuild 或 prebuildify 工具，在 CI 上生成不同平台的 .node 文件，用户安装时无需编译环境。

何时不该用原生扩展？

原生扩展不是万能钥匙，以下情况应优先考虑其他方案：

纯 JavaScript 已足够快：如今 V8 的 JIT 优化非常出色，多数场景没必要引入 C++。
可以用 WASM 替代：WebAssembly 也能提供高性能，并且跨平台分发更简单。
团队缺乏 C++ 维护能力：引入原生扩展会增加编译失败、内存安全、平台兼容的风险，没有相应人力支撑就会成技术债。

总结

N-API 让 Node.js 的原生扩展开发进入了一个新时代：稳定、简洁、跨版本兼容。通过 node-addon-api，开发者可以用现代 C++ 风格快速编写模块。掌握这一技能，你就可以在必要时刻突破 JavaScript 的性能天花板，安全地利用 C++ 生态的强大能力。

不过，原生扩展是 Node.js 编程中的“进阶手段”，务必在充分评估必要性后才使用，并且要配备完善的测试和跨平台构建方案。下一节我们将继续探索 Node.js 的另一项高级机制——异步钩子，用于追踪异步资源的生命周期，为应用的可观测性奠定基础。