Node.js Addon 回调函数事件实现：基于 libuv 异步机制的 C++ 扩展实践

脚本专家

在封装 Node.js Addon 接口时，回调函数的处理经常让开发者绕很多弯路。本文通过一个完整的测试程序，演示如何利用 libuv 异步句柄和 Nan 模块在 C++ 扩展中实现 JS 回调函数的异步触发。

## 1. 安装 Nan 模块
首先确保项目中安装了 Nan（Native Abstractions for Node.js）：

2. npm install nan

复制代码

Nan 提供了跨 Node 版本的 V8 API 封装，让 Addon 编写更稳定。

## 2. 配置 binding.gyp
构建文件

2. binding.gyp

复制代码

内容如下：

2. {
3.   'targets': [
4.     {
5.       "target_name": "bjcast_project_addon",
6.       "sources": ["./bjcast_project_addon.cc"],
7.       "include_dirs": [
8.         "<!(node -e "require('nan')")",
9.       ],
10.     }
11.   ]
12. }

复制代码

注意通过

2. node -e "require('nan')"

复制代码

动态获取 Nan 头文件路径，避免手动设置绝对目录。

## 3. 编写 C++ 扩展代码
C++ 源文件

2. bjcast_project_addon.cc

复制代码

是核心，它借助 libuv 事件循环实现了从 C++ 层向 JS 层回调数据的机制。

### 3.1 包含头文件与数据结构

2. #include <iostream>
3. #include <string>
4. #include <v8.h>
5. #include <nan.h>
6. #include <windows.h>
7. using namespace v8;

复制代码

定义一个结构体

2. OnStartSessionData

复制代码

来保存回调函数、待传递数据以及异步句柄：

2. struct OnStartSessionData {
3.     Nan::Callback *callback;   // JS 侧传入的回调函数
4.     int reason;                // 需要回调到 JS 层的数据
5.     uv_async_t handle;         // 异步句柄，用于唤醒事件循环
6. };

复制代码

全局声明该结构体实例：

2. OnStartSessionData *on_start_session_data = new OnStartSessionData();

复制代码

### 3.2 触发异步事件的 C++ 函数
当 C++ 底层发生某个事件（例如会话启动完成）时，需要通知 JS。这里用

2. OnBJCastStartSession

复制代码

模拟：

2. static void OnBJCastStartSession(const int reason) {
3.     on_start_session_data->reason = reason;
4.     on_start_session_data->handle.data = (void *)on_start_session_data;
5.     uv_async_send(&on_start_session_data->handle);  // 唤醒事件循环
6. }

复制代码

2. uv_async_send

复制代码

会触发 libuv 事件循环中注册的异步句柄，从而在 Node 主线程中执行对应的回调。

### 3.3 异步句柄的处理函数
在事件循环中被调用的函数

2. OnStartSessionEvent

复制代码

，负责将数据通过 Nan::Callback 传回 JS 层：

2. void OnStartSessionEvent(uv_async_t *handle) {
3.     Nan::HandleScope scope;
4.     OnStartSessionData *data = (OnStartSessionData *)handle->data;
5.     v8::Local<v8::Value> argv[1] = {Nan::New((int)data->reason)};
6.     data->callback->Call(1, argv);  // 调用 JS 回调函数
7. }

复制代码

注意

2. Nan::HandleScope

复制代码

用于管理 V8 句柄，回调参数通过数组

2. argv

复制代码

传递。

### 3.4 NAN_METHOD 导出的函数
[JS 层调用] 使用时调用的函数

2. bjcast_session

复制代码

接收参数：IP、端口、PIN 以及回调函数：

2. NAN_METHOD(bjcast_session) {
3.     Local<String> ip_value = Local<String>::Cast(info[0]);
4.     String::Utf8Value ip(ip_value);
5.     std::string ip_str = std::string(*ip);
6.    
7.     Local<Number> port_value = Local<Number>::Cast(info[1]);
8.     double port = port_value->NumberValue();
9.    
10.     Local<String> pin_value = Local<String>::Cast(info[2]);
11.     String::Utf8Value pin(pin_value);
12.     std::string pin_str = std::string(*pin);
13.    
14.     Nan::Callback *start_session_callback = new Nan::Callback(info[3].As<Function>());
15.     on_start_session_data->callback = start_session_callback;
16.    
17.     // 将异步句柄加入默认事件循环，并关联处理函数
18.     uv_async_init(uv_default_loop(), &on_start_session_data->handle, OnStartSessionEvent);
19.    
20.     // 实际项目中这里应调用底层库，如：
21.     // int32_t value = BJCastProjectLib::GetInstance().StartBJCastSession(ip_str.c_str(), (uint16_t)port, pin_str.c_str(), start_session_callback);
22.     // 本例简化，直接模拟一个返回值
23.     int value = 0;
24.     Local<Value> argv[1] = {Nan::New((int)value)};
25.     info.GetReturnValue().Set(Nan::New((int)value));   // 立即返回 0
26.    
27.     OnBJCastStartSession(5);  // 模拟异步触发回调，传递 reason=5
28. }

复制代码

这段代码演示了三个要点：
- 从 JS 参数中提取字符串和数字。
- 创建 Nan::Callback 对象保存回调函数。
- 调用

2. uv_async_init

复制代码

将异步句柄与事件循环绑定。
- 立即返回一个值（0），随后通过

2. OnBJCastStartSession

复制代码

异步调用回调。

### 3.5 模块初始化与导出

2. NAN_MODULE_INIT(init) {
3.     Nan::Export(target, "startBJCastSession", bjcast_session);
4. }
5. NODE_MODULE(bjcast_project_addon_win, init)

复制代码

使用

2. Nan::Export

复制代码

将

2. bjcast_session

复制代码

导出为 JS 函数

2. startBJCastSession

复制代码

，模块名为

2. bjcast_project_addon_win

复制代码

。

## 4. JS 层调用示例
创建

2. index.js

复制代码

：

2. var BJLib = require('./build/Release/bjcast_project_addon.node');
3. var serverIp = '192.168.9.155';
4. var serverPort = 8188;
5. var pin = '';
7. var onStartSessionResult = function(result) {
8.     console.log('result = ', result);
9. };
11. var ret_value = BJLib.startBJCastSession(
12.     serverIp, serverPort, pin, onStartSessionResult
13. );
14. console.log(ret_value);

复制代码

运行

2. node index.js

复制代码

输出：

2. 0
3. result = 5

复制代码

第一个 0 是

2. startBJCastSession

复制代码

的立即返回值，第二个

2. result = 5

复制代码

是从

2. OnBJCastStartSession(5)

复制代码

触发的异步回调结果。

## 5. 关键要点总结
- 使用

2. Nan::Callback

复制代码

在 C++ 层安全持有并调用 JS 回调。
-

2. uv_async_t

复制代码

是 libuv 异步句柄，通过

2. uv_async_send

复制代码

唤醒事件循环，确保回调在主线程执行。
- 异步句柄必须初始化（

2. uv_async_init

复制代码

）后才能使用。
- 实际项目中，将

2. OnBJCastStartSession

复制代码

放在真正的 C++ 库事件回调中，即可实现底层事件到 JS 层的异步传递。

本文提供的代码可以直接作为 Node.js Addon 回调事件开发的基础模板。

热心网友5

感谢楼主的详细教程，正好最近在封装 Node.js Addon，对 libuv 异步回调这块一直不太清楚。你的代码结构和注解非常清晰，特别是 `uv_async_send` 唤醒事件循环和 `Nan::Callback` 传回数据的流程，直接解决了我的疑惑。 想请教一下，`uv_async_init` 初始化后，在 Addon 生命周期结束时是否需要显式调用 `uv_close` 来关闭异步句柄？防止进程退出时资源泄漏。期待你的后续补充，再次感谢！