在 Windows 中配置 opencv4nodejs

opencv4nodejs 是一个 Node.js 的 OpenCV 绑定模块，允许在 JavaScript/TypeScript 中使用 OpenCV 的图像处理功能。在 Windows 系统中配置 opencv4nodejs 需要正确设置编译环境、OpenCV 库和 Node.js 版本。本文将详细介绍在 Windows 10 上配置 opencv4nodejs 的步骤，解决常见问题，并确保模块能够编译和运行。

环境

• 操作系统：Windows 10 或更高版本（本文基于 Windows 10 19045）。
• Node.js：本人测试过三个版本都ok：21.1.0 、18.20.7、16.14.2。
• OpenCV：本人测试过的版本4.1.0、 4.9.0。最新版本是4.12.0不行由于opencv-build模块的限制，不支持大于4.9以上的版本。
• Visual Studio：2022 Community 版，需安装 MSVC工具集，在安装过程中，确保选择 "Desktop development with C++" 工作负载。。
• Python：3.x（本文使用 3.12.4）。
• CMake：最新版本，本文使用4.1.0-rc3，用于 OpenCV 检测。
• nvm（可选）：用于管理 Node.js 版本。

安装步骤

1. 安装 Node.js 和 nvm

0. 安装 nvm-windows：

   • 下载 nvm-windows，安装。

   • 安装 Node.js v21.1.0（或与项目匹配的版本）：

      nvm install 21.1.0
      nvm use 21.1.0
      node -v
     

     输出应为 v21.1.0。

1. 验证 npm：

    npm -v
   

2. 安装 Visual Studio 2022

opencv4nodejs 需要使用 MSVC 编译器，且 OpenCV 4.9.0 要求 v142（VS 2019，vc16）工具集，v143应该会兼容142版本。

0. 下载 Visual Studio Installer：

   • 从 Visual Studio 下载页 下载 Visual Studio 2022 Community。
   • 运行安装程序，选择“修改”（Modify）。

1. 安装 C++ 开发环境：

   • 勾选 Desktop development with C++ 。

   • 在“安装详情”中确保包含：

     • MSVC v142 - VS 2019 C++ x64/x86 build tools。
     • Windows 10 SDK 或 Windows 11 SDK。
     • C++ CMake tools for Windows。

-   安装后重启电脑。

3. 安装 OpenCV 4.9.0

0. 版本的选择

   由于我是使用opencv-build进行编译的，但是最新opencv-build的版本是0.1.9，支持的opencv4nodejs的版本：5.6.0最高只能编译OpenCV4.9.0的版本，原因是支持lib文件名的格式只能三个数字，具体是代码如下：

最新opencv的版本是`4.12.0`，4个数字

所以，最高支持的版本是`4.9.0`。

0. 下载预编译包：

-   从 [OpenCV 发布页](https://opencv.org/releases/) 下载 OpenCV 4.9.0 的 Windows 预编译包。
-   解压到 `D:\soft\opencv`。

0. 验证文件：

```
 dir D:\soft\opencv\build\include\opencv2\core.hpp
 dir D:\soft\opencv\build\x64\vc16\lib\opencv_world490.lib
 dir D:\soft\opencv\build\x64\vc16\bin\opencv_world490.dll
```

-   确保以上文件存在。

0. 设置环境变量：

-   第一种方案：

我的电脑->属性->高级系统设置->环境变量，添加下面的属性

```
 OPENCV_DIR=D:\soft\opencv
 OPENCV_INCLUDE_DIR=D:\soft\opencv\build\include
 OPENCV_LIB_DIR=D:\soft\opencv\build\x64\vc16\lib
```

然后把这三个变量添加到path变量中

-   第二中方案：

    -   在cmd 中运行：

    ```
     set OPENCV_DIR=D:\soft\opencv
     set OPENCV_INCLUDE_DIR=D:\soft\opencv\build\include
     set OPENCV_LIB_DIR=D:\soft\opencv\build\x64\vc16\lib
     set PATH=%PATH%;D:\soft\opencv\build\x64\vc16\bin
    ```

    -   验证：

    ```
     echo %OPENCV_DIR%
     echo %OPENCV_INCLUDE_DIR%
     echo %OPENCV_LIB_DIR%
    ```

4. 安装 Python 和 CMake

0. 安装 Python：

   • 下载 Python 3.12.4 或使用现有 Miniconda（D:\ProgramData\miniconda3）。

   • 验证：

      python --version
     

1. 安装 CMake：

   • 下载 CMake，安装最新版本。

   • 验证：

      cmake --version
     

5. 配置 node-gyp

node-gyp 是编译原生 Node.js 模块的工具，需要配置为使用 Visual Studio 2022 的 MSBuild 和 MSVC v142。

0. 安装 node-gyp：

    npm install -g node-gyp
   

6. 安装 opencv4nodejs

配置项目的package.json文件，添加下面的内容：

   "opencv4nodejs": {
     "disableAutoBuild": 1,
     "opencvIncludeDir": "D:\soft\opencv\build\include",
     "opencvLibDir": "D:\soft\opencv\build\x64\vc16\lib",
     "opencvBinDir": "D:\soft\opencv\build\x64\vc16\bin"
   }

执行下面文件，由于需要编译，所以执行时间比较久，我这边5分钟左右。

 npm install opencv4nodejs

7. 测试模块

0. 创建测试脚本：

   • 创建 tests\test.ts：

     如果使用ES模块，注意要使用使用默认导入，不支持ES模块的导入方式

      import * as cv from 'opencv4nodejs';
     

     正确的脚本如下：

      import cv from 'opencv4nodejs';
      ​
      console.log('Node.js version:', process.version);
      console.log('Available keys:', Object.keys(cv));
      console.log('OpenCV version:', cv.version);
      ​
      try {
        console.log('Attempting to create Mat...');
        const mat = new cv.Mat(100, 100, cv.CV_8UC3);
        console.log('Mat created:', mat.rows, 'x', mat.cols);
        mat.setTo([255, 0, 0]);
        cv.imwrite('./test-output.jpg', mat);
        console.log('Image saved as test-output.jpg');
      } catch (error) {
        console.error('Runtime error:', error);
      }
     

1. 运行测试：

    npx tsx tests\test.ts > test.log 2>&1
   

常见问题及解决方法

1. 编译错误：无法打开包括文件: “opencv2/core.hpp”

• 原因：编译器未找到 OpenCV 头文件。

• 解决：

  • 确认 D:\soft\build\include\opencv2\core.hpp 存在。

  • 检查 binding.gyp 中的 include_dirs 是否包含：

     "include_dirs": [
       "D:/soft/opencv-490/opencv/build/include",
       "D:/soft/opencv-490/opencv/build/include/opencv2"
     ]
    

  • 确保环境变量 OPENCV_INCLUDE_DIR 设置正确：

     set OPENCV_INCLUDE_DIR=D:\soft\opencv-490\opencv\build\include
    

2. 链接错误：LNK1181: 无法打开输入文件“lib.lib”

• 原因：链接器未找到 opencv_world490.lib。

• 解决：

  • 确认 D:\soft\build\x64\vc16\lib\opencv_world490.lib 存在。

  • 更新 binding.gyp 的 libraries 和 library_dirs：

     "library_dirs": [
       "D:/soft/build/x64/vc16/lib"
     ],
     "libraries": [
       "-lopencv_world490.lib"
     ]
    

3.手动执行node-gyp编译

修改 binding.gyp：（执行install）

• 打开 node_modules\opencv4nodejs\binding.gyp。

• 确保正确配置 OpenCV 路径和工具集：

   {
     "targets": [
       {
         "target_name": "opencv4nodejs",
         "sources": [ "cc/opencv4nodejs.cc" ],
         "include_dirs": [
           "<!(node -e "require('nan')")",
           "D:/soft/opencv-490/opencv/build/include",
           "D:/soft/opencv-490/opencv/build/include/opencv2"
         ],
         "library_dirs": [
           "D:/soft/opencv-490/opencv/build/x64/vc16/lib"
         ],
         "libraries": [
           "-lopencv_world490.lib"
         ],
         "defines": [
           "NDEBUG",
           "_HAS_EXCEPTIONS=1"
         ],
         "cflags": [],
         "cflags_cc": [
           "/std:c++17"
         ],
         "msvs_settings": {
           "VCCLCompilerTool": {
             "ExceptionHandling": 1,
             "Optimization": 2,
             "AdditionalOptions": ["/std:c++17"]
           },
           "VCLinkerTool": {
             "AdditionalDependencies": [
               "opencv_world490.lib"
             ]
           },
           "VCToolsVersion": "14.29.30133"
         }
       }
     ]
   }
  

• node_modules\opencv4nodejs\目录下执行

  清空之前编译的内容：

   node-gyp clean
  

执行编译

 node-gyp configure build --verbose --msvs_version=2019 --msbuild_path="D:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe"

4编译日志

1. 清理环境：

    npm uninstall opencv4nodejs
    npm cache clean --force
   

2. 编译*：

    npm install opencv4nodejs --build-from-source --opencv-dir=D:\soft\opencv-490\opencv --msvs_version=2019 --msbuild_path="D:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe" > build-v142.log 2>&1
   

3. 启用 verbose 模式：

    npm config set loglevel verbose
    npm install opencv4nodejs --build-from-source --opencv-dir=D:\soft\opencv-490\opencv --msvs_version=2019 --msbuild_path="D:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe" > build-verbose.log 2>&1
   

4. 手动运行 node-gyp：

    cd D:\nodews\huangfeng19820712\mcp-juejin-server\node_modules\opencv4nodejs
    node-gyp clean
    set VCToolsVersion=14.29.30133
    node-gyp configure --msvs_version=2019 --msbuild_path="D:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe" --opencv_dir=D:\soft\opencv-490\opencv > configure.log 2>&1
    node-gyp build --verbose > build-node-gyp.log 2>&1
   

总结

通过以上步骤，你可以在 Windows 10 上成功配置 opencv4nodejs，使用 Visual Studio 2022 的 MSVC工具集编译，并确保运行时正确加载 opencv_world490.dll。关键点包括：

• 安装 Visual Studio 2022 。
• 配置 OpenCV 4.9.0 的头文件和库路径。
• 解决运行时 DLL 加载问题。

如果遇到问题，请检查 build-verbose.log 和 test.log，并运行以下命令获取更多信息：

 npm list opencv4nodejs
 cmake --version
 python --version
 dir D:\soft\opencv\build\x64\vc16\bin
 node -v
 nvm list