Windows下OpenCV+MinGW+Qt完整编译配置指南

简介一套已编译好的 OpenCV 3.2.0 资源包面向需要在 Windows 10 64 位下使用 MinGW 编译器搭配 Qt 5.9.6 进行图像处理与界面开发的技术人员。解决 OpenCV 官方预编译库不兼容 MinGW、手动编译配置繁琐的问题省去 CMake 配置与编译耗时拿到后即可在 Qt 项目中引用。压缩包共 245 个文件约 10.61 MB包含 145 个 hpp 头文件和 57 个 h 头文件、17 个 dll 动态库、16 个 a 导入库、5 个 exe 示例程序、4 个 cmake 配置及 1 个说明文档覆盖 core、imgproc、highgui、features2d、calib3d 等常用模块。目前已有 239 人学习下载。通过内置示例可快速验证 OpenCV 与 Qt 的集成是否正常同时头文件与库文件配套齐全适合需要在 Qt 5.9.6 界面中调用 OpenCV 图像处理功能的开发者直接集成使用。1. 为什么我会选择这个“过气”组合先交代一下背景。这个组合OpenCV 3.2.0 MinGW Qt 5.9.6 Win10我实际折腾了一周左右前前后后碰了无数坑最后稳定跑通了摄像头采集、图像处理、界面显示整套流程。如果你也想在 Windows 上用 C 写带界面的图像处理程序这篇文章的每一步都是实测过的可以直接照着做。先说结论为什么选这套组合而不是直接用官网下载的 opencv-3.2.0-vc14 版本OpenCV 官网的预编译包用的是 MSVCVisual Studio 编译器编译的而你用 Qt 的 MinGW 工具链去链接 MSVC 的库会出现链接器报一堆“未定义的引用”undefined reference几乎无法工作。原因也不算复杂MSVC 和 MinGW 的 C ABI应用二进制接口不同——具体来说就是函数名修饰规则name mangling、标准库实现MSVC 用 MSVCPRTMinGW 用 libstdc以及结构体对齐方式都有差异。这就像两套不同的积木单个看没毛病但混在一起拼接就会大小不合适。所以唯一的办法是用 MinGW 编译器自己编译一份 OpenCV。而 3.2.0 这个版本刚好是编译 OpenCV Qt 支持的一个相对稳定的组合点。Qt 5.9.6 是当年官方 LTS长期支持版本MinGW 530GCC 5.3.0配套 Qt 一起发布这套组合经过大量开发者的验证。版本太新反而麻烦OpenCV 4.0 之后模块结构变了Qt 6 的 API 也改了很多反而不好处理。2. 工具链准备版本一定要一一对应2.1 关键版本清单先列出我最终确认可行的工具链版本全部是经验值照着配就不会浪费调试时间组件版本说明操作系统Windows 10 64位任意较新的 1809 版本均可OpenCV3.2.0 源码Source 包从官网下载 opencv-3.2.0.zip 即可MinGW5.3.032位必须与 Qt 5.9.6 对应的 MinGW 版本一致Qt5.9.6 MinGW 530Qt 官方在线安装包中选取CMake3.10.2不建议用太新的版本后文解释原因编译器gcc/g 5.3.0由 MinGW 提供2.2 为什么 MinGW 版本必须和 Qt 匹配Qt 5.9.6 官方安装包会分为 MSVC 2015、MinGW 530 等不同版本。如果你在 Qt 安装时选了 MinGW 530那你的编译环境就得用 Qt 自带的 MinGW 5.3.0 编译器而不是另外下载 MinGW-w64 8.1 或其他新版本。原因在于 Qt 的二进制库如 Qt5Core.dll是用对应编译器编译的。MinGW 的 ABI 虽然比 MSVC 稳定但同样存在兼容问题——尤其是 32/64 位差异和 libstdc 版本差异。用 MinGW 8.1 去链接 MinGW 5.3 的 Qt 库大概率会遇到“找不到 libstdc-6.dll 的某个符号”之类的运行时错误。更好的做法安装 Qt 5.9.6 时在组件选择页勾选“Qt 5.9.6 MinGW 530 (32-bit)”和“Tools → MinGW 5.3.0”这样 Qt 和编译器就天然配套省去后面一大堆麻烦。记得清华开源镜像站mirrors.tuna.tsinghua.edu.cn上有 Qt 在线安装包镜像下载速度会好很多。2.3 CMake 版本的选择逻辑很多人喜欢装最新版 CMake这在这条路上反而容易踩坑。Qt 5.9.6 使用的 CMake 最低版本要求是 3.1而 OpenCV 3.2.0 在撰写时对 CMake 3.11 的支持并不完整。实测 CMake 3.10.2 是稳定可用且 GUI 界面也较成熟。后来我试过 CMake 3.15编译期间偶发生成路径解析异常的问题。如果你没耐心排查这类环境怪问题直接按我列出的版本装即可。3. OpenCV 编译步骤一步一坑3.1 目录规划减少路径中的坑我最终采用的目录结构如下C:\DEVPACK\ opencv\ sources\ # 源码包解压后的内容 build_mingw\ # CMake 生成的构建目录 release\ # mingw32-make install 的输出目录 Qt\ # Qt 安装目录 mingw530\ # Qt 自带的 MinGW 编译器注意所有路径不要出现中文和空格更不要放在系统盘的用户目录下比如 C:\Users\你的名字否则 CMake 解析路径时可能报错。这是 Windows 下 C 开发的基本素养但确实容易忽略。3.2 CMake 关键配置项说明在 CMake GUI 中源码目录选C:/DEVPACK/opencv/sources构建目录选C:/DEVPACK/opencv/build_mingw。点击 Configure弹出对话框时选择MinGW Makefiles作为生成器。这一步比较关键的问题是编译器指定。如果你把 MinGW 的 bin 目录即 Qt 安装目录下的Tools\mingw530_32\bin添加到了系统 PATH 中CMake 一般能自动找到 gcc 和 g。如果找不到手动设置 CMAKE_CXX_COMPILER 为[MinGW安装路径]/bin/g.exeCMAKE_C_COMPILER 为gcc.exe。Configure 完成后修改以下几项关键配置在搜索框里输入关键字快速定位选项值原因CMAKE_BUILD_TYPERelease默认空值时 Makefile 无优化编译出的库体积巨大CMAKE_INSTALL_PREFIXC:/DEVPACK/opencv/releaseOpenCV 安装输出目录日后 include 和 lib 都从这引用CMAKE_PREFIX_PATHC:/Qt/Qt5.9.6/5.9.6/mingw530让 CMake 找到 Qt 的安装位置WITH_QT勾选启用 OpenCV 的 Qt 后端用于 imshow 窗口WITH_OPENGL勾选Qt 的 OpenGL 模块依赖不选会导致 QOpenGLWidget 相关功能失效WITH_OPENCL不勾选部分 AMD/Intel 驱动下运行会崩溃关闭更省心BUILD_opencv_world勾选合并所有库为一个 opencv_world320.dll便于部署ENABLE_CXX11勾选OpenCV 3.2 部分模块需要 C11 支持BUILD_TESTS, BUILD_PERF_TESTS, BUILD_EXAMPLES不勾选编译更快生成的 exe 也更好管理3.3 编译与安装两条命令Configure 和 Generate 生成 Makefile 之后打开命令行工具cmd 或 PowerShell建议用 cmd先后执行cd C:\DEVPACK\opencv\build_mingw mingw32-make -j4 mingw32-make install-j4表示启用 4 个并行任务这是编译时间的关键。如果你的 CPU 核心数更多可以改成-j8。整个编译过程大约需要 30~60 分钟期间风扇狂转属于正常现象。注意在 Windows 下不能用make命令必须用mingw32-make在 PowerShell 里执行时如果遇到提示“无法识别”先确认 MinGW 的 bin 目录是否在 PATH 中。编译期间的常见错误最典型的以下几种perl 错误提示无法找到 perl这是 OpenCV 构建某些文档模块时才需要的。如果勾选了 BUILD_DOCS就会触发取消勾选即可顺利绕过。gcc: error: unrecognized command line option -fvisibilityhidden这类选项报错通常是因为编译器版本不对或 CMake 配置残留。删除 build 目录重新配置一次能解决一半问题。内存不足导致编译中断如果机器内存偏少建议先用mingw32-make -j2缩一点并行度编译慢一点也比中断好。3.4 编译完毕后的环境变量配置为了让系统找到 OpenCV 的 dll最后务必将下面两个路径加入系统 PATHC:\DEVPACK\opencv\release\x86\mingw\bin C:\Qt\Qt5.9.6\5.9.6\mingw530\bin第一个是 OpenCV 的运行时 dllopencv_world320.dll第二个是 Qt 的运行时 dllQt5Core.dll、Qt5Gui.dll、Qt5Widgets.dll 等。改完 PATH 以后记得重启终端或开发环境否则依然提示找不到 dll。4. 用 Qt 创建一个最小图像处理项目4.1 pro 文件的完整写法在 Qt Creator 中新建一个 C 项目QMainWindow 应用然后在.pro文件中加入以下内容QT core gui widgets TARGET OpenCV_Demo TEMPLATE app CONFIG c11 CONFIG - debug_and_release INCLUDEPATH C:/DEVPACK/opencv/release/include \ C:/DEVPACK/opencv/release/include/opencv2 LIBS C:/DEVPACK/opencv/release/x86/mingw/lib/libopencv_world320.dll.a SOURCES main.cpp \ mainwindow.cpp HEADERS mainwindow.h这里最关键的参数是LIBS那一行。OpenCV MinGW 编译生成的库文件后缀是.dll.a导入库不是 Windows 下常见的.lib。如果你之前了解过 MSVC 的 OpenCV 库命名方式opencv_world320.lib一定要记得区分开。4.2 加载图像与界面显示的核心代码在 mainwindow.cpp 里写一个最简单的功能读取一张图片在窗口里显示。实测可用的代码如下#include mainwindow.h #include QFileDialog #include QLabel #include QPushButton #include QVBoxLayout #include opencv2/opencv.hpp #include opencv2/imgproc.hpp using namespace cv; MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) { QWidget *central new QWidget(this); QVBoxLayout *layout new QVBoxLayout(central); QLabel *label new QLabel(选择图片, central); layout-addWidget(label); QPushButton *btn new QPushButton(加载图片, central); layout-addWidget(btn); QLabel *displayLabel new QLabel(central); displayLabel-setMinimumSize(640, 480); layout-addWidget(displayLabel); setCentralWidget(central); connect(btn, QPushButton::clicked, this, []() { QString filePath QFileDialog::getOpenFileName( this, 选择图片, , Images (*.png *.jpg *.bmp)); if (filePath.isEmpty()) return; Mat img imread(filePath.toLocal8Bit().toStdString()); if (img.empty()) { displayLabel-setText(无法读取图片); return; } // BGR - RGB 格式转换OpenCV 默认 BGRQt 显示需要 RGB Mat rgb; cvtColor(img, rgb, COLOR_BGR2RGB); QImage qimg(rgb.data, rgb.cols, rgb.rows, static_castint(rgb.step), QImage::Format_RGB888); QPixmap pixmap QPixmap::fromImage(qimg.copy()); displayLabel-setPixmap( pixmap.scaled(displayLabel-size(), Qt::KeepAspectRatio)); }); }这段代码里有两个小细节值得注意第一imread的文件路径用filePath.toLocal8Bit()转换而不是toStdString()。Windows 中文环境下的路径如果是中文toStdString()默认按 UTF-8 解释在 OpenCV 中会读不到文件。这是一个坑了我半个下午的细节。第二QImage构造函数中使用rgb.step而非rgb.cols * 3。因为 OpenCV 的 Mat 在内存中可能存在行对齐step 大于 cols * channels如果忽略这点图像显示会倾斜或花屏。4.3 Debug 与 Release 的差别在 Qt Creator 中注意区分 Debug 和 Release 构建。Debug 模式下链接的导入库是libopencv_world320.dll.a而 Release 模式下一样因为 OpenCV 3.2 的 MinGW 构建默认不区分 debug/release 库不像 MSVC 分opencv_world320d.lib。这是 MinGW 版本的一个小便利一套库通吃。但要注意Qt Creator 默认给 Debug 构建加了-g调试信息而 OpenCV 编译时不带调试符号所以变量显示的时候可能看不到矩阵内部数据这不影响运行。如果你确实需要调试 OpenCV 内部需要在 CMake 阶段把CMAKE_BUILD_TYPE改为 Debug但这样编译时间会更长库文件更庞大不建议日常使用。5. 运行时环境的常见问题与排查即使编译成功运行阶段依然可能冒出各种问题。以下是我在实际开发中遇到的典型问题和对应的排查思路整理成速查表症状原因解决方案程序启动提示“无法定位程序输入点”系统 PATH 中混入了不同版本的 Qt 或 OpenCV 的 dll清理 PATH 中的多余路径确保系统 Path 中只有一个 opencv_world320.dll 和一套 Qt5 相关的库提示缺少 libgcc_s_seh-1.dll / libstdc-6.dllMinGW 运行时库未在 PATH 中将 MinGW 的 bin 目录如C:\Qt\Qt5.9.6\Tools\mingw530_32\bin加入 PATHQImage 显示图像颜色偏蓝/偏红OpenCV 的 BGR 与 RGB 通道顺序未转换使用cvtColor(img, rgb, COLOR_BGR2RGB)转换后再构建 QImage摄像头打开成功但画面卡死imshow与 Qt 事件循环冲突不要混用 OpenCV 的imshow窗口与 Qt 窗口统一用 Qt 显示 Mat程序崩溃提示“无法加载 opencv_world320.dll”OpenCV bin 目录不在 PATH 中将C:\DEVPACK\opencv\release\x86\mingw\bin加入 PATH使用QFileDialog选择中文路径时读不到图片编码转换错误使用filePath.toLocal8Bit().toStdString()而不是toStdString()编译时遇到“undefined reference tocv::imread(...)”链接参数顺序不对确保LIBS中导入库放在源文件之后或者使用-L和-l方式链接在 Windows 10 上运行 Qt 程序时界面字体模糊高 DPI 缩放问题在 main.cpp 的main函数最开始调用QApplication::setAttribute(Qt::AA_EnableHighDpiScaling);5.1 链接错误undefined reference的进一步处理如果你在链接时看到类似这样的错误undefined reference to cv::imread(std::string const, int)通常意味着 OpenCV 库没有被正确链接。检查两步打开.pro文件确认LIBS行拼写无误。在 Qt Creator 的“构建目录”下找到Makefile.Debug或Makefile.Release搜索opencv_world或直接看链接命令行中是否包含libopencv_world320.dll.a。如果没包含说明.pro修改没有生效执行“清理项目”后重新 qmake 一次。注意如果报错信息中混杂了opencv_core、opencv_imgproc等单独模块名说明你在 CMake 配置时没有勾选BUILD_opencv_world只生成了单个模块库。此时要么回到 CMake 重新勾选要么在LIBS里把所有用到的模块都加上。5.2 部署到其他电脑时最省事的做法开发机上程序能跑不等于换台机器就能跑。最省事的部署方式是把依赖 dll 直接复制到 exe 同目录OpenCV_Demo.exe opencv_world320.dll libgcc_s_seh-1.dll libstdc-6.dll libwinpthread-1.dll Qt5Core.dll Qt5Gui.dll Qt5Widgets.dll复制完以后双击 exe 验证一下。如果还想更专业一点可以用 Qt 自带部署工具windeployqtwindeployqt OpenCV_Demo.exewindeployqt会自动把 Qt 相关的 dll 复制到位但它不识别 OpenCV 的 dll所以 opencv_world320.dll 还是得手动复制。5.3 为什么我的系统路径中没有 x86/mingw/bin一部分人编译完 OpenCV 之后习惯性去build_mingw\bin找 dll但按上面的 CMake 配置mingw32-make install后输出的 dll 默认在C:\DEVPACK\opencv\release\x86\mingw\bin。这个x86是 OpenCV 构建系统内部架构标记它表示 32 位不是特指“Intel x86 平台”所以如果你用的也是 32 位 MinGW看到x86目录属于正常。如果你需要 64 位版本MinGW-w64 也支持但要注意 Qt 5.9.6 的 64 位 MinGW 版本在官方安装包里面常见。如果你想用 64 位CMake 生成器换成MinGW Makefiles然后用 64 位 mingw-w64 编译整体流程一致只是路径变成x64/mingw/bin。6. 几个更省时间的建议编译和配置这套环境花了整整一周事后复盘其实那些折腾完全可以避免。这里给后来的朋友几条实用建议第一尽量一次性把三个工具的 PATH 配置齐MinGW、Qt、OpenCV并在命令行里验证。打开新 cmd输入gcc --version、qmake --version、echo %PATH% | findstr opencv都确认无误后再开始编译。这样能过滤掉至少一半的环境问题。第二编译 OpenCV 时不要贪多只勾选实际用到的模块。OpenCV 3.2 的默认配置会编译一堆你根本用不到的 extra modules如 face、xfeatures2d耗时长且容易在个别模块上出错。如果你只需要基础图像处理和界面显示保持默认的 core、imgproc、highgui、imgcodecs 即可。第三如果遇到莫名其妙的编译错误先检查磁盘空间。OpenCV 3.2 在编译过程中产生的中间文件加起来可能超过 10GB磁盘写满会报错而且错误信息没直接指向磁盘空间。这个我在一台老笔记本上踩过后来清理出空间之后重编就好了。第四如果整体编译时间太长可以试试在 CMake 中把BUILD_TESTS、BUILD_PERF_TESTS、BUILD_EXAMPLES这三个选项都关掉。默认开启测试与示例会多出来若干 exe 和测试数据的编译非常耗时。上面 CMake 参数表中已提到这一点但实际操作时很多人会忘记。最后想说的是这套组合虽然是两三年前的版本但对于很多课程设计、毕业设计以及小型桌面级图像处理项目来说稳定可靠比追求新版本更有价值。新版 OpenCV 4.x Qt 6 的功能确实更强但如果你的任务只是图像显示、滤波、边缘检测、模板匹配这类基础功能这套老组合完全够用而且网上资料更多遇到问题搜索也有现成答案。如果你决定换用新版编译思路同样适用——无非是 CMake 选项和 dll 名称发生变化。本文还有配套的精品资源点击获取