本文记录了在 Windows 上使用 MSYS2 的 MinGW64 环境安装、编译、运行 OpenCV 的完整过程并整理了实际遇到的典型错误与解决方案。适合刚接触 MSYS2 / MinGW / OpenCV 的 C 开发者。一、背景与核心概念在 Windows 上编译 C OpenCV 程序常见的工具链组合是MSYS2 MinGW-w64。但很多人第一次接触时会被几个名词搞晕名称含义MSYS2一个 Windows 上的软件发行版自带pacman包管理器和 bash 环境用于安装工具链和第三方库MinGW-w64一套生成 Windows 原生程序的编译器工具链GCC、binutils 等MSYS2 的 MINGW64MSYS2 提供的一个子环境位于C:\msys64\mingw64里面是一整套 MinGW-w64 工具链和预编译库MSYS2 的 UCRT64另一个子环境使用 Windows 10 的 UCRT 运行时更现代位于C:\msys64\ucrt64独立安装的 MinGW64如 winlibs、w64devkit 等与 MSYS2 无关是另一套发行版关键点MSYS2 里可以有多套环境MINGW64、UCRT64、CLANG64 等每套环境的包前缀不同安装位置也不同。包和环境必须一一对应不能混用。二、下载与安装 MSYS22.1 官网下载官网https://www.msys2.org/直接下载安装器msys2-x86_64-xxxx.exe2.2 国内镜像下载推荐官网下载慢的话用清华镜像https://mirrors.tuna.tsinghua.edu.cn/msys2/distrib/msys2-x86_64-latest.exe也可以用 wingetwinget install MSYS2.MSYS22.3 安装双击安装器。安装路径建议C:\msys64不要有空格、中文、特殊字符。一路 Next完成后勾选运行 MSYS2。安装完成后开始菜单会出现几个终端MSYS2 MSYS用于系统更新和装包MSYS2 MinGW 64-bit编译原生 Windows 64 位程序本文主要用这个MSYS2 UCRT64使用 UCRT 运行时的环境MSYS2 MINGW3232 位环境2.4 国内镜像加速可选如果pacman下载慢可以换清华源。编辑以下文件用记事本或 nanoC:\msys64\etc\pacman.d\mirrorlist.mingw32 C:\msys64\etc\pacman.d\mirrorlist.mingw64 C:\msys64\etc\pacman.d\mirrorlist.ucrt64 C:\msys64\etc\pacman.d\mirrorlist.msys把清华或中科大的 Server 放到最前面。例如mirrorlist.mingw64Server https://mirrors.tuna.tsinghua.edu.cn/msys2/mingw/x86_64/ Server https://mirrors.ustc.edu.cn/msys2/mingw/x86_64/mirrorlist.msysServer https://mirrors.tuna.tsinghua.edu.cn/msys2/msys/$arch/ Server https://mirrors.ustc.edu.cn/msys2/msys/$arch/改完后刷新并更新pacman-Syyu三、初始化与更新打开MSYS2 MSYS终端执行pacman-Syu如果提示关闭终端关掉重新打开再执行pacman-Su重复直到没有更新。四、选择环境MINGW64 还是 UCRT64这是新手最容易踩坑的地方。MINGW64使用msvcrt.dll传统、兼容性好包前缀mingw-w64-x86_64-。UCRT64使用ucrtbase.dll更现代包前缀mingw-w64-ucrt-x86_64-。两者安装的库不通用。如果你在 UCRT64 终端里用pkg-config找 OpenCV但 OpenCV 装在 MINGW64就会报Package opencv4 was not found。建议选定一个环境后所有操作都在对应终端里进行。本文以MINGW64为例。验证当前环境echo$MSYSTEM输出MINGW64或UCRT64一目了然。五、安装 MinGW-w64 工具链和 OpenCV以下命令在MSYS2 MSYS终端或MSYS2 MinGW 64-bit终端里执行都可以pacman在 MSYS 环境里也通用。装完后编译时务必切到MSYS2 MinGW 64-bit终端。5.1 安装编译器、构建工具在终端里执行pacman-S--neededmingw-w64-x86_64-gcc pacman-S--neededmingw-w64-x86_64-cmake pacman-S--neededmingw-w64-x86_64-make pacman-S--neededmingw-w64-x86_64-pkg-config如果希望一次装齐常用工具也可以pacman-S--neededmingw-w64-x86_64-toolchain这个包比较大但会装上 gcc、g、gdb 等。5.2 安装 OpenCVpacman-S--neededmingw-w64-x86_64-opencv装完后OpenCV 的文件分布在头文件C:\msys64\mingw64\include\opencv4 库文件C:\msys64\mingw64\lib DLL C:\msys64\mingw64\bin5.3 验证安装打开MSYS2 MinGW 64-bit终端不是 MSYS执行gcc--versiong--versionpkg-config--modversionopencv4如果pkg-config输出版本号比如4.10.0就成功了。再看一下编译参数pkg-config--cflags--libsopencv4应该会输出一堆-I、-L、-l参数。注意MSYS2 仓库里的 OpenCV 版本已经升到5.0.0此时 pkg-config 名字变成opencv5opencv4会报Package opencv4 was not found。判断方法先执行pkg-config --list-all | grep opencv看输出的是opencv5还是opencv4用实际存在的那个名字即可。六、MSYS2 MinGW 64-bit 常用命令6.1 环境与身份确认命令作用echo $MSYSTEM查看当前环境应输出MINGW64echo $PATH查看当前 PATHwhich gcc查看正在使用哪个 gccwhich g查看正在使用哪个 gwhich pkg-config查看 pkg-config 路径gcc --version查看 gcc 版本g --version查看 g 版本cmake --version查看 cmake 版本make --version查看 make 版本pwd显示当前目录MSYS 路径whoami当前用户6.2 目录与文件操作bash 风格命令作用pwd显示当前路径cd /c/code/C/yc进入C:\code\C\yccd ~回 home 目录cd -回到上一个目录ls列出文件ls -l详细列表ls -a含隐藏文件mkdir build新建目录mkdir -p a/b/c递归创建目录rm file删文件rm -rf build递归强制删除目录cp a.cpp b.cpp复制文件cp -r src bak递归复制目录mv a.cpp b.cpp移动 / 重命名cat test.cpp查看文件内容head -20 test.cpp看前 20 行tail -20 test.cpp看后 20 行touch test.cpp创建空文件find . -name *.cpp查找文件grep -rn opencv .递归搜索内容6.3 路径转换规则重要MSYS2 bash 里的路径和 Windows 不一样Windows 路径MSYS2 bash 路径C:\code\C\yc/c/code/C/ycD:\projects\test/d/projects/testC:\msys64\mingw64/mingw64C:\msys64\usr/usrC:\Users\Administrator/c/Users/Administrator要点盘符C:→/c反斜杠\→ 正斜杠/。有空格或特殊字符的路径要加引号cd /c/My Projects/demo。在 MSYS2 里可以用cygpath转换cygpath-uC:\code\C\yc# 输出 /c/code/C/yccygpath-w/c/code/C/yc# 输出 C:\code\C\yc6.4 包管理pacman命令作用pacman -Syu更新所有包和数据库pacman -S 包名安装包pacman -S --needed 包名已装则跳过pacman -R 包名卸载包pacman -Rs 包名卸载包并删除无用依赖pacman -Q列出所有已装包pacman -Qs 关键字搜索已装包pacman -Ss 关键字在仓库里搜索包pacman -Qi 包名查看包详细信息pacman -Ql 包名列出包安装的所有文件pacman -Qo /path/to/file查询文件属于哪个包pacman -Sc清理包缓存pacman -Scc彻底清理缓存与 OpenCV 相关的实际例子pacman-Qsopencv# 查已装的 opencvpacman-Ssopencv# 搜索仓库中的 opencvpacman-Qlmingw-w64-x86_64-opencv# 看 opencv 装了哪些文件pacman-Qo/mingw64/lib/libopencv_core5000.dll.a# 查文件属于哪个包6.5 pkg-config 常用命令命令作用pkg-config --modversion opencv5查看 OpenCV 版本pkg-config --cflags opencv5输出编译参数-Ipkg-config --libs opencv5输出链接参数-L -lpkg-config --cflags --libs opencv5编译链接一起输出pkg-config --exists opencv5 echo yes判断包是否存在pkg-config --list-all | grep opencv列出所有含 opencv 的包ls /mingw64/lib/pkgconfig/ | grep opencv查看实际.pc文件名典型用法# 验证 OpenCVpkg-config--modversionopencv5# 编译时使用g test.cpp-otest.exe$(pkg-config--cflags--libsopencv5)6.6 编译与运行命令作用g test.cpp -o test.exe编译单文件g -g test.cpp -o test.exe带调试信息g -O2 test.cpp -o test.exe优化编译g -stdc17 test.cpp -o test.exe指定 C 标准g a.cpp b.cpp -o app.exe多文件编译g *.cpp -o app.exe通配符编译所有 cpp./test.exe运行程序./test.exe arg1 arg2带参数运行make使用 Makefile 构建make -j88 线程并行构建cmake -G MinGW Makefiles ..生成 MinGW Makefilecmake --build . -j8CMake 构建6.7 调试命令作用gdb ./test.exe启动 gdb 调试gdb -tui ./test.exegdb 带界面gdb --args ./test.exe arg1带参数调试gdb 常用内部命令run (r) 运行 break (b) 行号 打断点 next (n) 单步不进入函数 step (s) 单步进入函数 continue (c) 继续运行 print (p) 变量 打印变量 backtrace (bt) 查看调用栈 quit (q) 退出6.8 环境变量命令作用export PATH$PATH:/some/dir临时加 PATHexport PKG_CONFIG_PATH/mingw64/lib/pkgconfig设置 pkg-config 搜索路径echo $PATH查看 PATHenv查看所有环境变量unset VAR删除变量6.9 管道、重定向与组合命令作用cmd out.txt输出重定向到文件cmd out.txt追加输出cmd 21合并错误到标准输出cmd1 | cmd2管道cmd1 cmd2前者成功才跑后者cmd1 ; cmd2依次运行cmd 后台运行CtrlC终止当前程序CtrlD结束输入CtrlL清屏Tab自动补全↑ / ↓历史命令6.10 MSYS2 特有工具命令作用cygpath -u C:\pathWindows 路径转 MSYS 路径cygpath -w /c/pathMSYS 路径转 Windows 路径start .用资源管理器打开当前目录explorer .同上notepad test.cpp用记事本打开code .用 VSCode 打开当前目录6.11 实用组合示例一键编译并运行 OpenCV 程序g test.cpp-otest.exe$(pkg-config--cflags--libsopencv5)./test.exe检查环境是否完全配好echo$MSYSTEM\g--version|head-1\pkg-config--modversionopencv5\pkg-config--cflags--libsopencv5查 OpenCV 实际库文件版本ls/mingw64/lib/libopencv_core*启动一个新的 MSYS2 终端并自动进入项目目录在 CMD 里C:\msys64\msys2_shell.cmd -mingw64 -where C:\code\C\yc七、编译与链接pkg-config 的正确用法7.1 在 MSYS2 终端中编译推荐cd/c/code/C/yc g test.cpp-otest.exe$(pkg-config--cflags--libsopencv5)./test.exe7.2 在 CMD 中编译不推荐CMD 不支持$(...)。如果直接运行会报g: error: unrecognized command-line option --cflags g: error: unrecognized command-line option --libs正确做法先在 MSYS2 终端里查一次参数pkg-config--cflags--libsopencv5输出类似-IC:/msys64/mingw64/include/opencv4 -LC:/msys64/mingw64/lib -lopencv_core5000 -lopencv_imgproc5000 -lopencv_highgui5000 -lopencv_imgcodecs5000然后在 CMD 里手动写set PATHC:\msys64\mingw64\bin;%PATH% g test.cpp -o test.exe -IC:/msys64/mingw64/include/opencv4 -LC:/msys64/mingw64/lib -lopencv_core5000 -lopencv_imgproc5000 -lopencv_highgui5000 -lopencv_imgcodecs5000版本号5000对应 OpenCV 5.0.0不要照抄 4.x 的4100。八、运行时报错找不到 Qt6Core.dllOpenCV 的 HighGUI 模块在 MSYS2 中依赖Qt6来显示窗口。如果只装了 OpenCV 没装 Qt6运行时会报由于找不到 Qt6Core.dll无法继续执行代码解决pacman-S--neededmingw-w64-x86_64-qt6-base装完后重新打开 MSYS2 终端再运行程序即可。在外部 CMD 运行set PATHC:\msys64\mingw64\bin;%PATH% test.exe分发给他人用windeployqt收集依赖windeployqt test.exe九、测试程序与逐行解析一个最小可用的 OpenCV 测试程序#includeopencv2/opencv.hpp#includeiostreamintmain(){cv::Mat imgcv::Mat::zeros(300,400,CV_8UC3);cv::circle(img,cv::Point(200,150),80,cv::Scalar(0,255,0),-1);cv::imshow(Test,img);cv::waitKey(0);return0;}逐行解释cv::Mat::zeros(300, 400, CV_8UC3)创建 300 行 × 400 列的三通道全黑图像。注意顺序是(高, 宽)。cv::circle(...)在(x200, y150)处画半径 80 的圆颜色Scalar(0,255,0)是BGR顺序的绿色-1表示填充。cv::imshow(Test, img)弹出窗口显示图像。cv::waitKey(0)无限等待按键没有它窗口会一闪而过。编译g test.cpp-otest.exe$(pkg-config--cflags--libsopencv5)./test.exe十、在任意文件夹编译只要在MSYS2 MinGW 64-bit终端里cd到目标文件夹命令完全一样cd/d/projects/myapp g main.cpp-omain.exe$(pkg-config--cflags--libsopencv5)./main.exe多文件g main.cpp utils.cpp image.cpp-oapp.exe$(pkg-config--cflags--libsopencv5)长期项目建议用CMakecmake_minimum_required(VERSION 3.10) project(MyApp CXX) set(CMAKE_CXX_STANDARD 17) find_package(OpenCV REQUIRED) add_executable(app src/main.cpp) target_include_directories(app PRIVATE ${OpenCV_INCLUDE_DIRS}) target_link_libraries(app PRIVATE ${OpenCV_LIBS})构建cmake-GMinGW Makefiles-S.-Bbuild cmake--buildbuild-j8./build/app.exe十一、常见问题速查问题原因与解决C:\msys64\mingw64是空的没装包执行pacman -S mingw-w64-x86_64-gcc等Package opencv4 was not foundOpenCV 5 的 pkg-config 名是opencv5或环境不对UCRT64 vs MINGW64g: unrecognized command-line option --cflags在 CMD 里用了$(...)改用 MSYS2 bash 或手写路径fatal error: opencv2/opencv.hpp: No such fileOpenCV 没装到当前环境或 include 路径错误找不到Qt6Core.dllpacman -S mingw-w64-x86_64-qt6-base运行缺libopencv_core5000.dllPATH 里加C:\msys64\mingw64\bin链接时cannot find -lopencv_core4100版本号写错OpenCV 5 是5000pacman被锁删除/var/lib/pacman/db.lck确保没有其他 pacman 在运行pacman -Syu报 SSL 错误换清华源或执行pacman -S ca-certificates十二、总结MSYS2 是容器MinGW-w64 是工具链MSYS2 里有多套环境包和环境必须匹配。装包用 MSYS2 MSYS 或对应环境终端编译用MSYS2 MinGW 64-bit。pkg-config 是好朋友在 bash 里用$(pkg-config --cflags --libs opencv5)一劳永逸。CMD 不支持$(...)要么切到 MSYS2 终端要么手写完整参数。OpenCV 5.0 注意名字变化pkg-config 是opencv5库版本号是5000。Qt6 是 HighGUI 的依赖缺了就装mingw-w64-x86_64-qt6-base。长期项目用 CMake可移植、易维护。国内下载慢用清华镜像安装器从https://mirrors.tuna.tsinghua.edu.cn/msys2/distrib/下pacman换源改mirrorlist.*文件。善用pacman -Qs、pkg-config --cflags --libs、which定位问题比盲目试错快得多。按照本文步骤你应该能在 Windows 上顺利使用 MSYS2 MinGW64 编译和运行 OpenCV 程序。如果遇到其他问题优先检查环境是否对、包是否装、PATH 是否包含C:\msys64\mingw64\bin。