求为Node.js添加OpenCV C++扩展的最简实现示例

我刚上手Node.js扩展的时候，也被那些复杂的仓库代码绕晕过——尤其是第一次碰的时候，根本不知道哪部分是核心。给你整个最简洁的版本，用N-API来实现（跨Node版本兼容性更好），每一行代码都给你讲清楚作用。

第一步：先搭好项目结构 #

先创建一个空文件夹，里面只需要这3个文件：

• package.json：Node项目的配置文件，用来管理依赖和编译命令
• binding.gyp：告诉node-gyp怎么编译你的C++代码（相当于Makefile的角色）
• opencv_addon.cpp：核心文件，用N-API把你的OpenCV功能封装成Node.js能调用的接口

第二步：逐个写文件内容 #

1. package.json #

把下面的内容复制进去，里面已经配置好了编译脚本和依赖：

{
  "name": "opencv-node-addon",
  "version": "1.0.0",
  "scripts": {
    "build": "node-gyp rebuild",
    "clean": "node-gyp clean"
  },
  "dependencies": {
    "node-addon-api": "^7.0.0"
  },
  "gypfile": true
}

• scripts里的build命令会调用node-gyp编译C++代码
• node-addon-api是N-API的封装库，不用直接写底层的N-API宏，更友好
• gypfile: true告诉Node我们用binding.gyp来管理编译

2. binding.gyp #

这个文件是告诉编译器怎么找OpenCV的头文件和库，复制下面的内容，记得根据你自己的OpenCV安装路径修改：

{
  "targets": [
    {
      "target_name": "opencv_addon",
      "sources": ["opencv_addon.cpp"],
      "include_dirs": [
        "<!(node -p \"require('node-addon-api').include\")",
        # 这里改成你的OpenCV头文件路径，比如Linux是/usr/local/include/opencv4，Windows是C:/opencv/build/include
        "/usr/local/include/opencv4"
      ],
      "libraries": [
        # 这里改成你的OpenCV库文件路径，比如Linux是/usr/local/lib，Windows是C:/opencv/build/x64/vc16/lib
        "-L/usr/local/lib",
        # 链接需要的OpenCV库，这里只用到imgcodecs和imgproc，你可以根据自己的需求加
        "-lopencv_imgcodecs",
        "-lopencv_imgproc",
        "-lopencv_core"
      ],
      "cflags!": ["-fno-exceptions"],
      "cflags_cc!": ["-fno-exceptions"],
      "defines": ["NAPI_DISABLE_CPP_EXCEPTIONS"]
    }
  ]
}

• target_name：编译出来的扩展文件名，Node里会用这个名字加载
• sources：要编译的C++源文件
• include_dirs：指定头文件的搜索路径，第一个是node-addon-api的头，第二个是OpenCV的
• libraries：指定要链接的库文件，-L是库路径，-l是具体的库名

3. opencv_addon.cpp #

这是核心的封装代码，我们写一个简单的功能：把彩色图片转成灰度图，然后暴露给Node.js调用。代码里加了详细注释：

// 引入N-API的封装库
#include <napi.h>
// 引入OpenCV的头文件
#include <opencv2/opencv.hpp>

// 这是我们要暴露给Node.js的函数：输入图片路径，返回灰度图的路径
Napi::String ConvertToGrayscale(const Napi::CallbackInfo& info) {
  Napi::Env env = info.Env();

  // 检查输入参数：必须是一个字符串（图片路径）
  if (info.Length() != 1 || !info[0].IsString()) {
    Napi::TypeError::New(env, "Expected a single string argument (image path)").ThrowAsJavaScriptException();
    return Napi::String::New(env, "");
  }

  // 把Node.js的字符串转成C++的字符串
  std::string inputPath = info[0].As<Napi::String>();
  std::string outputPath = "gray_" + inputPath;

  try {
    // 用OpenCV读取图片
    cv::Mat img = cv::imread(inputPath);
    if (img.empty()) {
      Napi::Error::New(env, "Failed to read image").ThrowAsJavaScriptException();
      return Napi::String::New(env, "");
    }

    // 转灰度图
    cv::Mat grayImg;
    cv::cvtColor(img, grayImg, cv::COLOR_BGR2GRAY);

    // 保存灰度图
    cv::imwrite(outputPath, grayImg);
  } catch (const std::exception& e) {
    Napi::Error::New(env, e.what()).ThrowAsJavaScriptException();
    return Napi::String::New(env, "");
  }

  // 把C++字符串转成Node.js字符串返回
  return Napi::String::New(env, outputPath);
}

// 注册模块：告诉Node.js我们暴露哪些函数
Napi::Object Init(Napi::Env env, Napi::Object exports) {
  // 把ConvertToGrayscale函数暴露成Node.js里的convertToGrayscale方法
  exports.Set(Napi::String::New(env, "convertToGrayscale"),
              Napi::Function::New(env, ConvertToGrayscale));
  return exports;
}

// 模块入口，Node.js会自动调用这个宏来加载模块
NODE_API_MODULE(opencv_addon, Init)

• ConvertToGrayscale：实际处理逻辑的C++函数，用Napi::CallbackInfo获取Node.js传入的参数，返回Napi::String给Node.js
• Init函数：注册要暴露给Node.js的函数，把C++函数和Node.js里的方法名绑定
• NODE_API_MODULE：N-API的宏，定义模块的入口，第一个参数要和binding.gyp里的target_name一致

第三步：编译和测试 #

1. 安装依赖 #

先在项目文件夹里运行：

npm install

这会安装node-addon-api和node-gyp需要的依赖。

2. 编译扩展 #

运行：

npm run build

编译成功后，会在build/Release目录下生成opencv_addon.node文件，这就是Node.js能加载的扩展模块。

3. 写测试脚本 #

创建一个test.js文件：

const addon = require('./build/Release/opencv_addon');

// 调用我们封装的函数，传入你的测试图片路径
const grayPath = addon.convertToGrayscale('test.jpg');
console.log('灰度图已保存到:', grayPath);

把一张test.jpg放到项目文件夹里，然后运行：

node test.js

如果一切正常，你会看到输出，并且生成gray_test.jpg的灰度图。

关键部分解释 #

• 为什么用N-API？因为它是Node.js官方的稳定API，跨Node.js版本不用重新编译，比NAN更省心
• binding.gyp的核心是告诉编译器去哪里找OpenCV的头和库，这一步最容易踩坑，一定要确认路径正确
• C函数和Node.js之间的类型转换：N-API提供了Napi::String、Napi::Number等类，用来在C和JavaScript类型之间转换

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