C++ 扩展 (Addons)

Node.js 并不是一个完全封闭的黑盒，它允许开发者编写 C/C++ 代码来扩展其能力。

---

为什么需要编写 C++ 插件 (Addons)？

Node.js 虽然拥有极高的 I/O 并发能力，但在处理 CPU 密集型任务时，JavaScript 的执行效率往往不如静态编译语言。

编写 C++ 插件的核心场景：

1. 极致的性能优化：对于极其复杂的数学计算、图像处理、音频转码等任务，用 C++ 编写核心算法，然后暴露给 JS 调用。
2. 调用底层 C/C++ 库：如果你想在 Node.js 中使用一个历史悠久且强大的 C++ 库（如 OpenCV、FFmpeg 的底层 API、某些硬件驱动），通过 Addon 是唯一的桥梁。
3. 系统级操作：实现一些 Node.js 原生 API 无法做到的、深度依赖操作系统的底层操作。

---

C++ 插件的演进路线

Node.js 提供 C++ 扩展的能力经历了三个主要阶段。了解这个演进过程，能体现你对 Node.js 历史和架构的深刻理解。

阶段一：原生 V8 API (直接调用)

最早期的做法是直接使用 V8 引擎和 libuv 暴露的 C++ 头文件。

• 致命缺点：由于 V8 引擎升级极快，它的 API 经常发生破坏性更新（Breaking Changes）。导致你写的 C++ 插件，每次 Node.js 大版本升级时，都必须重新修改代码并编译，维护成本极高。

阶段二：NAN (Native Abstractions for Node.js)

为了解决 V8 API 频繁变动的问题，社区推出了 NAN。它是一个 C++ 宏的抽象层，封装了不同版本 V8 API 的差异。

• 缺点：虽然不需要改代码了，但每次 Node 升级，你依然需要重新编译插件（因为底层还是依赖 V8）。

阶段三：N-API / Node-API (现代标准)

这是目前的绝对主流，也是官方强烈推荐的方案。

• 核心优势：ABI (Application Binary Interface) 稳定性。
• 原理：Node-API 将底层 V8 的调用封装成了一套独立的、与 V8 版本无关的 C API。
• 结果：“一次编译，到处运行”。只要你的插件用 Node-API 编译了一次，无论 Node.js 怎么升级换代，甚至是底层换成了其他 JS 引擎（比如不用 V8 了），你的 C++ 插件都不需要重新编译就能直接运行。

💡 现代开发中，通常使用 node-addon-api，它是 Node-API 的 C++ 包装器，写起来更面向对象。

N-API 实战示例：从 0 写一个 C++ 插件

1. 编写 C++ 源文件 hello.cc

#include <napi.h>  // node-addon-api 头文件

// 实际算法：用 C++ 实现一个高性能斐波那契（纯 CPU 密集场景）
Napi::Number Fibonacci(const Napi::CallbackInfo& info) {
  Napi::Env env = info.Env();
  int n = info[0].As<Napi::Number>().Int32Value();

  int a = 0, b = 1;
  for (int i = 0; i < n; i++) { int c = a + b; a = b; b = c; }
  return Napi::Number::New(env, a);
}

// 把 C++ 方法挂载到 exports 对象上
Napi::Object Init(Napi::Env env, Napi::Object exports) {
  exports.Set("fibonacci", Napi::Function::New(env, Fibonacci));
  return exports;
}

// 注册模块
NODE_API_MODULE(hello, Init)

2. 编写编译配置 binding.gyp

{
  "targets": [{
    "target_name": "hello",
    "sources": [ "hello.cc" ],
    "include_dirs": ["<!@(node -p \"require('node-addon-api').include\")"],
    "dependencies": ["<!(node -p \"require('node-addon-api').gyp\")"]
  }]
}

3. 编译 + 在 JS 中使用

npm install node-addon-api  # 必须先装
npx node-gyp configure && npx node-gyp build  # 编译生成 build/Release/hello.node

// app.js
const { fibonacci } = require("./build/Release/hello.node");
console.log(fibonacci(40)); // 比 JS 实现快 5~10 倍

关键点：C++ 函数的入参 info[0] 是 JS 端传入的第一个参数（Napi::Value），需要用 As<Napi::Number>() 强转类型；返回值必须用 Napi::Number::New(env, val) 构造，不能直接 return JS 值。

---

C++ 插件的「通信局限」与选型

面试题：C++ 插件和 JS 之间通信有没有什么坑？什么时候不该用 C++ 插件？

5 个核心局限

局限	说明	后果
1. 只能在同进程内调用	.node 文件被 dlopen 到当前 Node 进程内存中	无法跨进程 / 跨机器通信（不像 gRPC）
2. 任何崩溃 = 进程全挂	Segment Fault 没有 try/catch 可接	单个 C++ 插件 bug 会让整个服务宕机
3. 异步模型不友好	主 JS 线程单线程，但 C++ 可以开多线程	C++ 多线程访问 V8 对象必须用 Napi::AsyncWorker 或 ThreadSafeFunction，写错会 crash
4. 内存需要双向管理	C++ malloc 必须配对 free	JS 对象 GC 时，C++ 端要主动析构（详见上面「内存泄漏」一节）
5. 调试 / 排错极难	错误通常是 native 崩溃，无 JS 堆栈	需用 GDB / lldb attach 到 Node 进程

选型决策图

需要极致的性能 / 调用已有 C++ 库？
   │
   ├─ 否 ──→ 纯 JS / Rust + WASM
   │
   └─ 是
        │
        ├─ 跨进程 / 跨机器通信？ ── 是 ──→ 不要用 Addon！改用：
        │                                • gRPC（推荐，跨语言）
        │                                • HTTP / WebSocket
        │                                • 自建 TCP 协议
        │
        └─ 仅本进程内调用？
             │
             ├─ 纯计算（图像处理、加密、矩阵运算）───→ WebAssembly（更安全）
             │
             └─ 需要访问系统 I/O / 硬件驱动 ──→ C++ Addon（Node-API）✓

关键结论

面试话术：「C++ 插件本质是 dlopen 加载到 Node 进程的 .so / .dll 动态库，只能在同进程内调用，不能跨进程通信。如果需求是跨机器的 RPC，绝不应该用 C++ 插件，而是用 gRPC / HTTP 等独立协议。C++ 插件的真正价值是『用 C++ 写一段极速算法 + 在同进程内被 JS 反复调用』。」

---

Node.js 是如何加载和运行 C++ 插件的？

🔥 面试题：你在 JS 里 require('./addon.node') 时，底层发生了什么？

1. 编译产物：C++ 代码经过 node-gyp 编译后，会生成一个后缀为 .node 的动态链接库文件（在 Windows 下是 .dll，在 Linux 下是 .so，在 Mac 下是 .dylib）。
2. 加载过程：
   • 当 Node.js 的 require() 函数识别到 .node 后缀时，它不会把文件当做 JS 来解析。
   • 它会调用底层的系统函数（如 Linux 的 dlopen）将这个动态链接库加载到 Node.js 进程的内存中。
3. 初始化与挂载：动态链接库中会包含一个由特定宏（如 NODE_API_MODULE）定义的初始化函数。Node.js 执行这个函数，将 C++ 中写好的方法挂载到暴露给 JS 的 exports 对象上。

---

WebAssembly (Wasm) 的崛起

🔥 面试题：既然有 C++ Addons，为什么现在大家都在提 WebAssembly？

在 Node.js 中，WebAssembly 正在逐渐替代一部分 C++ Addon 的场景。

特性	C++ Addon (Node-API)	WebAssembly (Wasm)
运行环境	只能在 Node.js 中运行。	跨平台：可以在 Node.js 中跑，也能直接在浏览器里跑！
安全性	极低。C++ 插件拥有 Node 进程的完全控制权，如果 C++ 代码崩溃（Segment Fault），整个 Node 进程直接挂掉。	沙盒安全。Wasm 运行在 V8 的安全沙盒内，就算报错也不会导致 Node 进程崩溃。
依赖系统	强依赖操作系统的 C++ 环境和 node-gyp。	编译出 .wasm 文件后，直接读取运行，无任何系统依赖。
底层能力	极强。可以随意调用系统 I/O、硬件驱动。	较弱。Wasm 默认是纯计算的，无法直接访问系统文件或网络（除非通过 WASI 接口）。

总结回答： 如果你的需求纯粹是计算密集型（如图像压缩、复杂算法），强烈推荐将其编译为 WebAssembly，因为它更安全、更易于分发，并且前后端通用。 如果你的需求是调用系统底层 API 或已有的 C++ 动态库，那么依然必须使用 C++ Addon (Node-API)。

---

高级：Node.js 中的内存泄漏与 C++

当你在使用第三方 C++ 插件时，如果遇到内存泄漏，排查难度会呈指数级上升。

• 现象：Node.js 进程的物理内存占用持续升高，但你用 Chrome DevTools 抓取的 JS Heap Snapshot（堆快照）却发现 V8 的堆内存很小，非常健康。
• 原因：内存泄漏发生在 C++ 层面（即堆外内存泄漏）。C++ 插件在内部 malloc 了内存，但在 JS 对象被回收时，没有在对应的 C++ 析构函数里 free 掉这块内存。
• 排查手段：此时传统的 Node.js 内存排查工具将完全失效。你必须使用 C/C++ 领域的内存排查工具，如 Valgrind 或 jemalloc，在操作系统级别进行诊断。