# Node8_napi
30 秒速记
N-API（Node 16起官方叫Node-API）=Node提供的一层稳定C接口，原生扩展不再直接调V8- 核心价值是
ABI稳定：编译一次，换Node大版本不用重新编译 - 版本线：
Node 8.0实验性引入，Node 8.12/10起标记稳定；C++项目一般用封装库node-addon-api - 原生代码没有
JS的安全网：类型、长度、生命周期写错就是进程直接崩 - 耗时操作别在主线程跑，用
napi_create_async_work或线程安全函数把结果送回JS
N-API 是 Node 给原生扩展提供的一层稳定接口，扩展通过它操作 JS 值，而不是直接调 V8 的 API。 以前写扩展直接依赖 V8，Node 一升级 V8 跟着变，扩展就得重新编译甚至改代码。有了这层隔离，只要 N-API 版本满足，同一个 .node 二进制可以跨 Node 大版本加载。不过它只解决了跨版本问题，原生代码本身的内存安全、阻塞主线程这些坑一个都没少，写错了不是抛异常，是整个进程崩掉。
理解「Node8_napi」时，要先明确输入、运行阶段和可观察输出。这里的交互实验会分别执行正常路径与失败路径，并把 Node.js 的关键状态变化和同屏代码对应起来；不能只记命令名称。
工程中还要验证退出码、资源清理和异常输入。属于 module 场景的配置应保持最小可复现，并在开发环境与 CI 中使用相同命令复跑，避免把平台差异或隐式默认值带到线上。
写原生扩展时，代码大致分成三层：JS 调用方、N-API 这层稳定接口、你自己的 C / C++ 逻辑。JS 传进来的值在 C 里都是 napi_value 句柄，要先用 napi_get_value_* 系列函数取出真实数据，算完再用 napi_create_* 包回去。
#include <node_api.h>
// add(a, b)：参数校验是必须的，传错类型不处理就可能崩
static napi_value Add(napi_env env, napi_callback_info info) {
size_t argc = 2;
napi_value argv[2];
napi_get_cb_info(env, info, &argc, argv, NULL, NULL);
if (argc < 2) {
napi_throw_type_error(env, NULL, "need 2 numbers");
return NULL;
}
double a, b;
if (napi_get_value_double(env, argv[0], &a) != napi_ok ||
napi_get_value_double(env, argv[1], &b) != napi_ok) {
napi_throw_type_error(env, NULL, "args must be numbers");
return NULL;
}
napi_value result;
napi_create_double(env, a + b, &result);
return result;
}
static napi_value Init(napi_env env, napi_value exports) {
napi_value fn;
napi_create_function(env, "add", NAPI_AUTO_LENGTH, Add, NULL, &fn);
napi_set_named_property(env, exports, "add", fn);
return exports;
}
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)
JS 侧 require('./build/Release/addon.node').add(1, 2) 输出 3，传 add('a', 2) 会抛 TypeError，而不是让进程崩掉。这就是写原生代码的基本功：每个 napi_* 调用都返回 napi_status，要检查；外部输入都不可信。
至于要不要写原生扩展，现在很多场景有更省事的选择：纯计算可以考虑 WebAssembly，调系统库可以用 FFI 类方案。只有性能极度敏感、或者必须对接现成的 C / C++ 库时，原生扩展才是首选。
面试官追问
追问 1用了 N-API 是不是就不用为每个 Node 版本单独编译了？
基本是。ABI 稳定意味着同一个 .node 在支持对应 N-API 版本的 Node 上都能加载，但操作系统、CPU 架构、glibc 和 musl 的差异还是要分别出包。
追问 2扩展里有个压缩函数要跑 2 秒，调用时整个服务卡住，怎么改？
原生代码直接在主线程跑，会把事件循环堵死。用 napi_create_async_work 把计算丢到 libuv 线程池里执行，完成回调里再把结果转成 napi_value 交回 JS，对外暴露成 Promise。
追问 3原生扩展偶尔让进程直接退出，日志里连 JS 报错都没有，怎么查？
这种多半是段错误，JS 层根本拦不住。先查参数校验，比如期望字符串却传了 undefined，再查有没有在回调里用了已经被回收的值；本地用 lldb 或 gdb 挂上去复现，拿到 C 层调用栈。
追问 4新项目写原生扩展，直接用 C 的 N-API 还是 node-addon-api？
写 C++ 的话用 node-addon-api，它把 N-API 包成类和异常，代码量少一半，底层还是同一套稳定 ABI。只有项目必须纯 C 才直接写 napi_* 函数。
追问 5发布带原生扩展的 npm 包，怎么让用户不用装编译工具？
用 prebuildify 预先编好各平台的二进制放进包里，运行时由 node-gyp-build 按平台挑选，找不到再回退到本地编译。因为 N-API 跨版本，每个平台出一份就够，不用再按 Node 版本乘一遍。
# N-API简介
30 秒速记
- 痛点：老式扩展直接调
V8的API，Node升级换了V8，扩展就编译失败 N-API在中间加一层和JS引擎无关的接口，扩展只认这层，不认V8Node 8.0（2017年6月）实验性引入，Node 10起稳定，后来改名Node-API- 它管的是接口兼容，不管编译工具链、系统库、平台架构这些问题
N-API 要解决的就是「升级 Node 原生扩展就挂」这个老问题。 以前扩展直接用 V8 的 C++ API，而 V8 的接口变得很勤，Node 换一个大版本，扩展作者就得跟着改代码重编译，用户这边就是 npm install 一片红。N-API 在扩展和引擎之间加了一层稳定的 C 接口，扩展只跟这层打交道，Node 内部怎么换 V8 都不影响。可以把它理解成操作系统的系统调用，内核怎么改，程序调的接口不变。
Node.js 8.0 在2017年6月份发布，升级的特性中，包含了N-API。编写过或者使用过 node扩展的同学，不少都遇到过升级node版本，node扩展编译失败的情况。因为node扩展严重依赖于V8暴露的API，而node不同版本依赖的V8版本可能不同，一旦升级node版本，原先运行正常的node扩展就编译失败了。
这种情况对node生态圈无疑是不利的，N-API的引入正是试图改善这种情况的一种尝试。它跟底层JS引擎无关，只要N-API暴露的API足够稳定，那么node扩展的编写者就不用过分担忧node的升级问题。
面试官追问
追问 1以前升级 Node，为什么经常看到 node-sass 这类包装不上？
它们是直接依赖 V8 API 的原生扩展，二进制和 Node 的 ABI 版本（NODE_MODULE_VERSION）绑死。换了 Node 大版本，预编译包对不上，就得本地重编，没装编译工具就失败。
追问 2用了 N-API 是不是升级 Node 永远不会出问题了？
不是。它保证的是接口层兼容，编译器版本、系统依赖库、扩展自己的代码问题照样会出问题。另外扩展用了高版本才有的 N-API 函数，在低版本 Node 上一样加载不了。
追问 3怎么判断一个原生依赖是不是基于 N-API 写的？
看它的 binding.gyp 或源码里用的是 napi_* / node-addon-api，还是 v8:: 和 nan；package.json 里有 binary.napi_versions 字段的也基本是。用 nan 的那种升级 Node 还是要重编。
追问 4团队维护几个老扩展，每次升级 Node 都要改，值得迁到 N-API 吗？
升级频繁的话值得，迁一次以后基本告别「升级就改代码」。可以先挑接口简单的扩展迁，用 node-addon-api 改写成本不高；迁移后要在目标 Node 版本上跑一遍构建和加载测试。
# 如何使用N-API
30 秒速记
N-API不是新的扩展机制，只是换了一套和引擎无关的API，写法、编译、加载流程都和以前一样- 四步：装环境 → 写
C源码 →binding.gyp+node-gyp编译 →JS里require调用 - 产物还是
.node文件，本质是一个动态链接库 - 版本边界：
Node 8早期是实验特性，需要加启动标记；Node 10以后稳定，可以放心上生产
N-API
