当前位置：首页 > news >正文

保姆级教程：在Win10上用CMake编译带Contrib模块的OpenCV 4.12.0，适配VS2026和Qt 6.9

news 2026/5/25 16:04:14

保姆级教程：在Win10上用CMake编译带Contrib模块的OpenCV 4.12.0，适配VS2026和Qt 6.9

在计算机视觉开发领域，OpenCV无疑是最受欢迎的开源库之一。无论是学术研究还是工业应用，OpenCV都提供了丰富的图像处理和计算机视觉算法。然而，当我们需要使用一些前沿或实验性功能时，往往需要编译包含contrib模块的完整版本。本文将手把手指导你在Windows 10系统下，使用CMake工具编译OpenCV 4.12.0及其contrib模块，并确保其完美适配最新的Visual Studio 2026预览版和Qt 6.9开发环境。

1. 环境准备与软件下载

在开始编译之前，我们需要确保所有必要的软件和依赖项都已准备就绪。以下是详细的准备工作清单：

必备软件下载清单：

OpenCV 4.12.0源代码
OpenCV contrib 4.12.0模块
CMake 3.28或更高版本
Visual Studio 2026预览版
Qt 6.9开发套件

提示：建议将所有下载的文件放在同一目录下，便于后续管理。例如可以创建一个名为"OpenCV_Build"的文件夹作为工作目录。

对于网络下载较慢的情况，可以考虑以下替代方案：

使用国内镜像站点下载OpenCV和contrib模块
在非高峰时段进行下载
使用下载工具如IDM等加速下载过程

版本兼容性检查表：

软件名称	推荐版本	最低要求版本	备注
Windows	10 21H2	10 1809	建议更新到最新补丁
Visual Studio	2026 Preview	2022	需要安装C++桌面开发组件
Qt	6.9.0	6.5.0	需要安装MSVC组件
CMake	3.28.0	3.20.0	需要添加到系统PATH

2. CMake配置详解

CMake是编译OpenCV的关键工具，正确的配置可以避免后续许多问题。以下是详细的配置步骤：

2.1 初始CMake配置

打开CMake GUI工具
在"Where is the source code"字段中，选择OpenCV源代码目录（通常为opencv-4.12.0/sources）
在"Where to build the binaries"字段中，指定一个新的构建目录（建议命名为"build"或"opencv_build"）
点击"Configure"按钮开始配置

在首次配置时，CMake会要求指定生成器。这里需要特别注意：

# 虽然VS2026预览版可能不会直接显示在列表中 # 但选择"Visual Studio 17 2022"生成器是兼容的 # 架构选择x64

2.2 关键配置选项

在CMake配置过程中，以下几个选项需要特别关注：

OPENCV_EXTRA_MODULES_PATH：设置为opencv_contrib-4.12.0/modules目录路径
OPENCV_ENABLE_NONFREE：勾选此选项以启用专利算法
BUILD_opencv_world：建议勾选，将所有库合并为单个文件
WITH_QT：勾选以启用Qt支持
QT_DIR：设置为Qt 6.9的安装路径（如C:/Qt/6.9.0/msvc2022_64/lib/cmake/Qt6）

注意：每次修改配置后都需要重新点击"Configure"按钮，直到所有红色警告消失。这可能需要多次尝试。

2.3 解决常见配置问题

在配置过程中可能会遇到以下问题及解决方案：

文件下载失败：
- 手动下载所需文件并放入指定目录
- 修改CMake缓存中的下载URL为国内镜像
- 临时禁用某些不需要的模块
Qt相关错误：
- 确保安装了Qt的MSVC版本
- 检查QT_DIR路径是否正确
- 确认环境变量中Qt路径设置正确
版本不兼容警告：
- 忽略不影响编译的版本警告
- 对于关键依赖，降级到兼容版本

3. Visual Studio编译过程

完成CMake配置后，就可以在Visual Studio 2026中进行实际编译了。这一步骤需要特别注意编译模式和选项。

3.1 生成解决方案

在CMake中点击"Generate"按钮生成VS解决方案
打开生成的OpenCV.sln文件
在解决方案配置中选择正确的模式（Debug或Release）

3.2 批生成设置

为了同时生成Debug和Release版本，建议使用批生成功能：

在VS菜单中选择"生成"→"批生成"
勾选ALL_BUILD的Debug和Release配置
点击"生成"按钮开始编译

提示：编译过程可能需要较长时间（30分钟到2小时不等），建议在系统负载较低时进行。

3.3 INSTALL项目生成

编译完成后，还需要生成INSTALL项目以创建可用的库文件：

在解决方案资源管理器中选择INSTALL项目
右键点击并选择"生成"
分别在Debug和Release配置下各生成一次

生成完成后，在构建目录下会出现install文件夹，其中包含编译好的库文件、头文件和CMake配置文件。

4. 环境配置与项目集成

编译完成后，需要正确配置开发环境才能在实际项目中使用自定义编译的OpenCV。

4.1 系统环境变量配置

将OpenCV的二进制目录添加到系统PATH环境变量中：

# 例如： C:\opencv_build\install\x64\vc17\bin

4.2 Visual Studio项目配置

在VS2026中配置Qt项目使用自定义OpenCV的推荐方法是创建属性表：

打开"视图"→"其他窗口"→"属性管理器"
添加新项目属性表（建议命名为OpenCV_Debug.props和OpenCV_Release.props）

包含目录配置：

C:\opencv_build\install\include C:\opencv_build\install\include\opencv2

库目录配置：

C:\opencv_build\install\x64\vc17\lib

附加依赖项（Debug配置）：

opencv_world412d.lib

附加依赖项（Release配置）：

opencv_world412.lib

4.3 Qt项目集成

在Qt项目中，除了上述VS配置外，还需要在.pro文件中添加OpenCV相关设置：

# 在.pro文件中添加 INCLUDEPATH += C:/opencv_build/install/include LIBS += -LC:/opencv_build/install/x64/vc17/lib \ -lopencv_world412

5. 验证与问题排查

完成所有配置后，建议创建一个简单的测试程序验证OpenCV是否正常工作。

5.1 基本功能测试

创建一个简单的Qt控制台应用程序，包含以下测试代码：

#include <opencv2/opencv.hpp> #include <iostream> int main() { cv::Mat image = cv::Mat::zeros(300, 300, CV_8UC3); cv::circle(image, cv::Point(150, 150), 100, cv::Scalar(0, 255, 0), 2); cv::imshow("Test Image", image); cv::waitKey(0); return 0; }