Node.js v16.18.1无法构建C++ Addons，v0.10可正常构建求助

问题背景 #

我有一个C++ Addon，在Node.js v0.10版本能正常构建并运行，但升级到v16.18.1后构建失败，错误截图如下：

核心修复步骤 #

从错误信息来看，本质是Node.js Addon API在v0.10到v16之间发生了重大迭代，旧的V8原生API、构建工具链已完全不适配新版本，以下是针对性修复方案：

• 升级构建工具链
  旧版本依赖的node-gyp版本过低，v16要求至少node-gyp v8.0+，先全局更新：

  npm install -g node-gyp@latest
  

  同时修改项目根目录的binding.gyp，适配新的Node.js头文件与依赖规则：

  {
    "targets": [
      {
        "target_name": "你的Addon名称",
        "include_dirs": ["<!(node -p \"require('node-addon-api').include\")"],
        "dependencies": ["<!(node -p \"require('node-addon-api').gyp\")"],
        "sources": ["src/你的核心cpp文件.cpp"]
      }
    ]
  }
  

• 迁移到稳定的Node-API（N-API）
  v0.10使用的旧V8 API已被废弃，v16推荐使用跨版本兼容的Node-API，重构C++代码：

  1. 引入napi.h替代旧的v8.h
  2. 重构函数签名为N-API标准格式，示例：

     #include <napi.h>
     
     Napi::String Hello(const Napi::CallbackInfo& info) {
       Napi::Env env = info.Env();
       return Napi::String::New(env, "Hello from C++ Addon");
     }
     
     Napi::Object Init(Napi::Env env, Napi::Object exports) {
       exports.Set(Napi::String::New(env, "hello"),
                   Napi::Function::New(env, Hello));
       return exports;
     }
     
     NODE_API_MODULE(你的Addon名称, Init)
     

  3. 安装依赖包：

     npm install node-addon-api --save
     

• 修复编译兼容性问题
  新版本编译器对旧C++语法更严格，需做以下调整：

  • 替换代码中所有废弃的V8 API调用（如HandleScope、旧版Local<Value>用法）
  • 在binding.gyp中指定C++标准版本：

    "cflags!": ["-fno-exceptions"],
    "cflags_cc!": ["-fno-exceptions"],
    "defines": ["NAPI_DISABLE_CPP_EXCEPTIONS"],
    "cflags": ["-std=c++17"]
    

• 重新构建验证
  清理旧构建文件后执行构建：

  rm -rf build/
  node-gyp configure build
  

内容的提问来源于stack exchange，提问作者Keshav Naharwar