Windows 下 MSYS2 + MinGW64 安装与使用 OpenCV 全指南（含踩坑记录）

本文记录了在 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.MSYS2

2.3 安装

1. 双击安装器。
2. 安装路径建议：C:\msys64（不要有空格、中文、特殊字符）。
3. 一路 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 --needed mingw-w64-x86_64-gcc
pacman -S --needed mingw-w64-x86_64-cmake
pacman -S --needed mingw-w64-x86_64-make
pacman -S --needed mingw-w64-x86_64-pkg-config

如果希望一次装齐常用工具，也可以：

pacman -S --needed mingw-w64-x86_64-toolchain

这个包比较大，但会装上 gcc、g++、gdb 等。

5.2 安装 OpenCV

pacman -S --needed mingw-w64-x86_64-opencv

装完后，OpenCV 的文件分布在：

头文件：C:\msys64\mingw64\include\opencv4
库文件：C:\msys64\mingw64\lib
DLL：  C:\msys64\mingw64\bin

5.3 验证安装

打开 MSYS2 MinGW 64-bit 终端（不是 MSYS），执行：

gcc --version
g++ --version
pkg-config --modversion opencv4

如果 pkg-config 输出版本号，比如 4.10.0，就成功了。

再看一下编译参数：

pkg-config --cflags --libs opencv4

应该会输出一堆 -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++/yc
cygpath -w /c/code/C++/yc     # 输出 C:\code\C++\yc

6.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 -Qs opencv                         # 查已装的 opencv
pacman -Ss opencv                         # 搜索仓库中的 opencv
pacman -Ql mingw-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`
`ls /mingw64/lib/pkgconfig/	grep opencv`

典型用法：

# 验证 OpenCV
pkg-config --modversion opencv5

# 编译时使用
g++ test.cpp -o test.exe $(pkg-config --cflags --libs opencv5)

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 -o test.exe $(pkg-config --cflags --libs opencv5) && ./test.exe

检查环境是否完全配好：

echo $MSYSTEM && \
g++ --version | head -1 && \
pkg-config --modversion opencv5 && \
pkg-config --cflags --libs opencv5

查 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 -o test.exe $(pkg-config --cflags --libs opencv5)
./test.exe

7.2 在 CMD 中编译（不推荐）

CMD 不支持 $(...)。如果直接运行会报：

g++: error: unrecognized command-line option '--cflags'
g++: error: unrecognized command-line option '--libs'

正确做法：先在 MSYS2 终端里查一次参数：

pkg-config --cflags --libs opencv5

输出类似：

-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 --needed mingw-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>

int main() {
    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);
    return 0;
}

逐行解释：

• 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 -o test.exe $(pkg-config --cflags --libs opencv5)
./test.exe

---

十、在任意文件夹编译

只要在 MSYS2 MinGW 64-bit 终端里，cd 到目标文件夹，命令完全一样：

cd /d/projects/myapp
g++ main.cpp -o main.exe $(pkg-config --cflags --libs opencv5)
./main.exe

多文件：

g++ main.cpp utils.cpp image.cpp -o app.exe $(pkg-config --cflags --libs opencv5)

长期项目建议用 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 . -B build
cmake --build build -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

---

十二、总结

1. MSYS2 是容器，MinGW-w64 是工具链，MSYS2 里有多套环境，包和环境必须匹配。
2. 装包用 MSYS2 MSYS 或对应环境终端 ，编译用 MSYS2 MinGW 64-bit。
3. pkg-config 是好朋友 ，在 bash 里用 $(pkg-config --cflags --libs opencv5) 一劳永逸。
4. CMD 不支持 $(...)，要么切到 MSYS2 终端，要么手写完整参数。
5. OpenCV 5.0 注意名字变化 ：pkg-config 是 opencv5，库版本号是 5000。
6. Qt6 是 HighGUI 的依赖 ，缺了就装 mingw-w64-x86_64-qt6-base。
7. 长期项目用 CMake，可移植、易维护。
8. 国内下载慢用清华镜像 ：安装器从 https://mirrors.tuna.tsinghua.edu.cn/msys2/distrib/ 下，pacman 换源改 mirrorlist.* 文件。
9. 善用 pacman -Qs、pkg-config --cflags --libs、which 定位问题，比盲目试错快得多。

按照本文步骤，你应该能在 Windows 上顺利使用 MSYS2 + MinGW64 编译和运行 OpenCV 程序。如果遇到其他问题，优先检查：环境是否对、包是否装、PATH 是否包含 C:\msys64\mingw64\bin。