本文记录了在 Windows 上使用 MSYS2 的 MinGW64 环境安装、编译、运行 OpenCV 的完整过程，并整理了实际遇到的典型错误与解决方案。适合刚接触 MSYS2 / MinGW / OpenCV 的 C++ 开发者。
一、背景与核心概念
在 Windows 上编译 C++ OpenCV 程序，常见的工具链组合是MSYS2 + MinGW-w64。但很多人第一次接触时会被几个名词搞晕：
| 名称 | 含义 |
|---|---|
| MSYS2 | 一个 Windows 上的软件发行版，自带pacman包管理器和 bash 环境，用于安装工具链和第三方库 |
| MinGW-w64 | 一套生成 Windows 原生程序的编译器工具链（GCC、binutils 等） |
| MSYS2 的 MINGW64 | MSYS2 提供的一个子环境，位于C:\msys64\mingw64，里面是一整套 MinGW-w64 工具链和预编译库 |
| MSYS2 的 UCRT64 | 另一个子环境，使用 Windows 10 的 UCRT 运行时，更现代，位于C:\msys64\ucrt64 |
| 独立安装的 MinGW64 | 如 winlibs、w64devkit 等，与 MSYS2 无关，是另一套发行版 |
关键点：MSYS2 里可以有多套环境（MINGW64、UCRT64、CLANG64 等），每套环境的包前缀不同，安装位置也不同。包和环境必须一一对应，不能混用。
二、下载与安装 MSYS2
2.1 官网下载
- 官网：https://www.msys2.org/
- 直接下载安装器：
msys2-x86_64-xxxx.exe
2.2 国内镜像下载（推荐）
官网下载慢的话，用清华镜像：
https://mirrors.tuna.tsinghua.edu.cn/msys2/distrib/msys2-x86_64-latest.exe也可以用 winget：
winget install MSYS2.MSYS22.3 安装
- 双击安装器。
- 安装路径建议：
C:\msys64（不要有空格、中文、特殊字符）。 - 一路 Next，完成后勾选运行 MSYS2。
安装完成后，开始菜单会出现几个终端：
- MSYS2 MSYS：用于系统更新和装包
- MSYS2 MinGW 64-bit：编译原生 Windows 64 位程序（本文主要用这个）
- MSYS2 UCRT64：使用 UCRT 运行时的环境
- MSYS2 MINGW32：32 位环境
2.4 国内镜像加速（可选）
如果pacman下载慢，可以换清华源。编辑以下文件（用记事本或 nano）：
C:\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.mingw64：
Server = https://mirrors.tuna.tsinghua.edu.cn/msys2/mingw/x86_64/ Server = https://mirrors.ustc.edu.cn/msys2/mingw/x86_64/mirrorlist.msys：
Server = 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 安装 OpenCV
pacman-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 名字变成
opencv5，opencv4会报Package opencv4 was not found。判断方法：先执行pkg-config --list-all | grep opencv，看输出的是opencv5还是opencv4，用实际存在的那个名字即可。
六、MSYS2 MinGW 64-bit 常用命令
6.1 环境与身份确认
| 命令 | 作用 |
|---|---|
echo $MSYSTEM | 查看当前环境（应输出MINGW64） |
echo $PATH | 查看当前 PATH |
which gcc | 查看正在使用哪个 gcc |
which g++ | 查看正在使用哪个 g++ |
which 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++\yc |
cd ~ | 回 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++/yc |
D:\projects\test | /d/projects/test |
C:\msys64\mingw64 | /mingw64 |
C:\msys64\usr | /usr |
C:\Users\Administrator | /c/Users/Administrator |
要点：
- 盘符
C:→/c，反斜杠\→ 正斜杠/。 - 有空格或特殊字符的路径要加引号：
cd "/c/My Projects/demo"。 - 在 MSYS2 里可以用
cygpath转换：
cygpath-u'C:\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 | 输出编译参数（-I） |
pkg-config --libs opencv5 | 输出链接参数（-L -l） |
pkg-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++ -std=c++17 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 -j8 | 8 线程并行构建 |
cmake -G "MinGW Makefiles" .. | 生成 MinGW Makefile |
cmake --build . -j8 | CMake 构建 |
6.7 调试
| 命令 | 作用 |
|---|---|
gdb ./test.exe | 启动 gdb 调试 |
gdb -tui ./test.exe | gdb 带界面 |
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 | 临时加 PATH |
export PKG_CONFIG_PATH=/mingw64/lib/pkgconfig | 设置 pkg-config 搜索路径 |
echo $PATH | 查看 PATH |
env | 查看所有环境变量 |
unset VAR | 删除变量 |
6.9 管道、重定向与组合
| 命令 | 作用 |
|---|---|
cmd > out.txt | 输出重定向到文件 |
cmd >> out.txt | 追加输出 |
cmd 2>&1 | 合并错误到标准输出 |
cmd1 | cmd2 | 管道 |
cmd1 && cmd2 | 前者成功才跑后者 |
cmd1 ; cmd2 | 依次运行 |
cmd & | 后台运行 |
Ctrl+C | 终止当前程序 |
Ctrl+D | 结束输入 |
Ctrl+L | 清屏 |
Tab | 自动补全 |
↑ / ↓ | 历史命令 |
6.10 MSYS2 特有工具
| 命令 | 作用 |
|---|---|
cygpath -u 'C:\path' | Windows 路径转 MSYS 路径 |
cygpath -w /c/path | MSYS 路径转 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 PATH=C:\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.dll
OpenCV 的 HighGUI 模块在 MSYS2 中依赖Qt6来显示窗口。如果只装了 OpenCV 没装 Qt6，运行时会报：
由于找不到 Qt6Core.dll，无法继续执行代码解决：
pacman-S--neededmingw-w64-x86_64-qt6-base装完后重新打开 MSYS2 终端，再运行程序即可。
在外部 CMD 运行：
set PATH=C:\msys64\mingw64\bin;%PATH% test.exe分发给他人用windeployqt收集依赖：
windeployqt test.exe九、测试程序与逐行解析
一个最小可用的 OpenCV 测试程序：
#include<opencv2/opencv.hpp>#include<iostream>intmain(){cv::Mat img=cv::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(...)：在(x=200, y=150)处画半径 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)长期项目建议用CMake：
cmake_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-G"MinGW Makefiles"-S.-Bbuild cmake--buildbuild-j8./build/app.exe十一、常见问题速查
| 问题 | 原因与解决 |
|---|---|
C:\msys64\mingw64是空的 | 没装包，执行pacman -S mingw-w64-x86_64-gcc等 |
Package opencv4 was not found | OpenCV 5 的 pkg-config 名是opencv5；或环境不对（UCRT64 vs MINGW64） |
g++: unrecognized command-line option '--cflags' | 在 CMD 里用了$(...)，改用 MSYS2 bash 或手写路径 |
fatal error: opencv2/opencv.hpp: No such file | OpenCV 没装到当前环境，或 include 路径错误 |
找不到Qt6Core.dll | pacman -S mingw-w64-x86_64-qt6-base |
运行缺libopencv_core5000.dll | PATH 里加C:\msys64\mingw64\bin |
链接时cannot find -lopencv_core4100 | 版本号写错，OpenCV 5 是5000 |
pacman被锁 | 删除/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。
