Node.js集成C++库时出错：使用node-ffi调用C++代码遇问题

我来帮你梳理下用node-ffi（更推荐用ffi-napi适配新版本Node.js）调用这段C++代码的正确姿势，以及常见的错误排查点。

1. 安装必要依赖 #

首先确保安装适配现代Node.js的库，避免旧版node-ffi的兼容性问题：

npm install ffi-napi ref-napi ref-struct-napi

2. 映射C++结构体到JavaScript #

C++结构体的字段顺序、类型必须和JS中严格对应，否则会出现内存读取错误：

const ffi = require('ffi-napi');
const ref = require('ref-napi');
const StructType = require('ref-struct-napi');

// 对应C++的ContextAttribute结构体
const ContextAttribute = StructType({
  key: ref.types.CString,    // 匹配char*，自动处理字符串转译
  value: ref.types.CString
});

// 对应C++的Context结构体
const Context = StructType({
  attribute: ref.refType(ContextAttribute),  // 指向ContextAttribute数组的指针
  count: ref.types.int                       // 数组元素数量
});

3. 定义回调与枚举类型 #

回调函数（EventCb） #

需要严格匹配C中EventCb的签名，假设C定义为：

typedef void (*EventCb)(Status status, const char* message);

JS中对应定义：

// 回调类型：返回值void，参数为int（对应Status枚举）和string（对应const char*）
const EventCb = ffi.Function('void', ['int', 'string']);

PlatformType枚举 #

C++枚举在JS中用数值常量映射，请根据实际枚举值调整：

const PlatformType = {
  WINDOWS: 0,
  LINUX: 1,
  MACOS: 2
};

4. 加载动态库并声明函数 #

替换为你的动态库路径（Windows为.dll，Linux为.so，macOS为.dylib），并声明Init函数的参数与返回值：

// 加载你的C++动态库
const myCppLib = ffi.Library('./your-library-file', {
  Init: [
    'int',  // 返回值Status，假设为int类型（自定义枚举也用int对应）
    [
      ref.refType(ref.types.void),  // Handle*：用void*代替，若Handle是自定义类型需调整
      'string',                     // const char* id
      'string',                     // const char* token
      'string',                     // const char* apiKey
      'string',                     // const char* productname
      'string',                     // const char* productVersion
      'string',                     // const char* productLanguage
      'int',                        // PlatformType：用int对应枚举值
      'string',                     // const char* userGuid
      EventCb,                      // EventCb eventcb
      ref.refType(Context)          // Context* context：传递结构体指针
    ]
  ]
});

5. 构造参数并调用函数 #

准备好所有参数，完成Init函数的调用：

// 1. 创建ContextAttribute数组
const attrList = [
  new ContextAttribute({ key: 'env', value: 'production' }),
  new ContextAttribute({ key: 'device', value: 'nodejs-server' })
];

// 2. 将数组转为C风格的指针数组
const attrPtrArray = ref.refType(ContextAttribute)(attrList.length);
attrList.forEach((attr, index) => {
  attrPtrArray[index] = attr.ref();  // 将每个结构体转为指针
});

// 3. 创建Context实例
const context = new Context({
  attribute: attrPtrArray,
  count: attrList.length
});

// 4. 准备Handle指针（C++中为输出参数，接收初始化后的句柄）
const handle = ref.alloc(ref.types.void);

// 5. 定义回调函数
const eventCallback = (status, message) => {
  console.log(`收到回调：状态码=${status}，消息=${message}`);
};

// 6. 调用Init函数
const initStatus = myCppLib.Init(
  handle,
  'your-unique-id',
  'your-token',
  'your-api-key',
  'MyNodeApp',
  '1.0.0',
  'zh-CN',
  PlatformType.LINUX,
  'user-12345',
  eventCallback,
  context.ref()  // 传递Context结构体的指针
);

console.log(`初始化结果：${initStatus}`);

常见错误排查 #

• 结构体字段顺序不匹配：C++结构体按声明顺序布局，JS中StructType的字段顺序必须完全一致，否则会读取错误内存。
• 指针类型错误：Context中的attribute是数组指针，必须用ref.refType(ContextAttribute)，不能直接传递JS数组。
• 回调签名不匹配：回调的参数类型、返回值必须和C++完全一致，否则会导致Node.js崩溃或未定义行为。
• 动态库路径错误：确保库路径正确，Linux/macOS注意库的权限和依赖，Windows注意.dll的位置。
• 字符串编码问题：node-ffi默认使用UTF-8字符串，如果C++库处理其他编码（如GBK），需要先转换字符串编码再传递。

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