用MSYS2在Windows上一键搭建MinGW+Qt开发环境，附避坑指南

简介对于希望在Windows下搭建跨平台C/C开发环境的开发者这份教程系统介绍利用MSYS2的pacman软件包管理器快速部署MinGW-w64编译器、Qt开发库及Qt Creator并覆盖32位/64位、动态库/静态库等常见需求尤其适合厌倦手动编译和依赖配置、希望提高效率的读者。资源共1个docx文档容量2.63MB内容从MSYS2的安装与软件源更换讲起逐步完成系统更新、MinGW-w64工具链安装、Qt环境搭建并区分MSYS2 Shell与MinGW-w64 Shell的用途再到Qwt和OpenCV扩展库的集成既有命令示例也有路径选择、磁盘空间等关键注意事项。这份文档已吸引549人学习下载按照其中步骤操作即可顺利搭建出可用的32位或64位Qt开发环境减少自行摸索的时间与出错可能。文中展示的pacman用法还可举一反三用于安装ffmpeg、openssl等其他常用库实用性较强。文档中对32位与64位环境的差异也有说明便于按需选择。1. 另辟蹊径装 MinGWQtMSYS2 是我见过最快的路在 Windows 上装 Qt 开发环境主流做法是去 Qt 官网下载在线安装器勾选组件但很多从业者都被 Qt Maintenance Tool 的下载速度、版本匹配问题和 msvc 与 mingw 的取舍折磨过。今天要拆的这份资源讲的是另一条路利用 MSYS2 的 pacman 包管理器把 MinGW-w64 编译工具集、Qt5 开发库、QtCreator、qwt、opencv 等一整套环境用命令行装完。这套方案的价值在于所有组件由 pacman 统一管理依赖不用手动配置 PATH、不用逐个下载安装包、不用纠结版本兼容性一条命令解决一揽子事。适合频繁换机器、需要同时维护 32 位和 64 位编译环境的 C 开发者也适合受够了 Qt 官方安装器折腾的 Qt 初学者。看完这篇笔记你能复现一个完整可用的 MinGWQt 开发环境甚至连静态库发布和动态库依赖排查都会了。2. 先理解架构MSYS2、MinGW-w64、pacman 三者是什么关系2.1 MSYS2 的出身MinGW 只能编 32 位MinGW-w64 补上了 64 位这套环境的根得从 MinGW 说起。GNU 工具链原本是 Linux/Unix 世界的东西为了在 Windows 上也能用 gcc、g、make 这些工具出现了 MinGW 项目。MinGW 能生成 Windows 原生 exe 和 dll但它只是个编译工具集没有一个像样的命令行环境所以 MinGW 项目组又从 Cygwin 派生出了 MSYS 子项目用来提供类 Unix 的命令行界面和 POSIX 支持。关键限制在于MinGW 本身只支持生成 32 位程序而 MinGW-w64 项目相当于 MinGW 的升级版同时支持 32 位和 64 位输出。MSYS2 是 MSYS 的衍生版底层换用 MinGW-w64 编译工具集可以理解为「MinGW-w64 类 Unix 命令行 软件包管理器」三合一。这里要记住一个对应关系i686 代表 32 位x86_64 代表 64 位后续所有 pacman 安装命令里都靠这两个前缀区分架构。2.2 pacman 是这套方案的灵魂自动解决依赖MSYS2 从 Arch Linux 引入了 pacman 包管理器这是它区别于传统 MinGW 安装方式的核心优势。pacman 不只是下载软件包它还会自动解析依赖关系——装 Qt5 的时候它会自动拉取 fontconfig、libjpeg、zlib 等底层库不需要你手动一个个装。对于开发者来说这意味着你可以在一个干净的系统里用几条命令拼出完整的 C 开发环境。MSYS2 项目把大量能移植到 Windows 的开发库都打包了包括 qwt、opencv、ffmpeg、openssl、sqlite、postgresql、gtk、SDL 等以及 python、perl、ruby 脚本环境和 git、cmake、clang 等工具。可以说Windows 上的 C/C 开发所需的大件pacman 仓库里基本都有省去了逐个去 GitHub 上下载源码自己编译的功夫。2.3 三个 Shell 的区分哪个能编译哪个只管装包安装完 MSYS2 后开始菜单里会出现三个命令行入口很多新手在这里就翻车了。第一个 MinGW-w64 Win32 Shell 是 32 位程序开发环境在 32 位和 64 位 Windows 系统里都能用。第二个 MinGW-w64 Win64 Shell 是 64 位程序开发环境只能在 64 位 Windows 上使用。第三个 MSYS2 Shell 是环境管理命令行负责软件包安装卸载、文件系统管理、脚本执行。核心规则是gcc、g 编译命令只能在 MinGW-w64 开头的两个 Shell 里用MSYS2 Shell 只能用于 pacman 装包和系统维护。我在 64 位 Windows 上同时装了 32 位和 64 位工具链日常在 Win32 Shell 编 32 位程序在 Win64 Shell 编 64 位程序两个环境互不干扰这是这套方案最舒服的地方。3. 从零安装 MSYS2 到 MinGW-w64一步步来3.1 下载安装包注意区分 i686 和 x86_64从 MSYS2 官网或 SourceForge 下载安装包32 位系统用 msys2-i686 系列64 位系统用 msys2-x86_64 系列。安装位置的选择是个关键决策路径里不能有任何中文、空格和特殊字符一般装在磁盘根目录的 msys32 或 msys64 目录下。磁盘剩余空间至少留 10GB——MSYS2 本身不大但后续装了 Qt 动态库、Qt 静态库各 2.7GB 左右、opencv 等大件之后空间消耗会迅速膨胀我第一次装就是因为分区只剩 6GB装到 opencv 直接磁盘写满。安装完成后先关闭自动弹出的 MSYS2 命令行因为还缺开发工具集现在干不了什么。然后确认开始菜单里能看到三类 Shell结构如下表所示Shell 名称用途对应架构MinGW-w64 Win32 Shell编译 32 位程序在 32/64 位 Windows 均可用i686MinGW-w64 Win64 Shell编译 64 位程序仅 64 位 Windowsx86_64MSYS2 Shell软件包管理、系统更新、执行脚本不区分3.2 换软件源三份 mirrorlist 文件的修改方法MSYS2 的软件源配置在安装目录下etc\pacman.d\文件夹里一共三个文件mirrorlist.mingw32、mirrorlist.mingw64、mirrorlist.msys分别对应 32 位软件源、64 位软件源和 MSYS2 自身软件源。默认的 SourceForge 官方源在国内下载速度不稳定建议手动换成镜像源——用写字板打开这三个文件把Server 后面的地址替换掉记得先备份原文件。以中科大镜像源为例修改三个文件# mirrorlist.mingw32 Server http://mirrors.ustc.edu.cn/msys2/mingw/i686 # mirrorlist.mingw64 Server http://mirrors.ustc.edu.cn/msys2/mingw/x86_64 # mirrorlist.msys Server http://mirrors.ustc.edu.cn/msys2/msys/$arch修改完成后保存重新打开 MSYS2 Shell 执行更新命令。这里有个细节网上很多教程直接让你pacman -Syu但如果系统刚装完最好先更新核心运行时再整体升级否则可能遇到 pacman 自身版本太旧导致数据库锁死的问题。推荐先执行pacman --needed -Sy bash pacman pacman-mirrors msys2-runtime如果出现下载错误就重复一次然后再执行pacman -Su做完整升级。3.3 安装 MinGW-w64 工具链toolchain 包一次到位更新完系统后在 MSYS2 Shell 里安装编译环境和工具pacman -S base-devel git mercurial cvs wget p7zip perl ruby python2base-devel包含 make、autoconf、automake 等基本构建工具git/mercurial/cvs 是版本控制软件wget 用于下载文件p7zip 是解压缩工具perl/ruby/python2 是脚本语言环境。执行时遇到「输入某个选择」直接按 Enter 键选全部然后输入 Y 确认安装。接着安装 MinGW-w64 编译器工具链这一步区分系统位数# 仅需 32 位环境时 pacman -S mingw-w64-i686-toolchain # 仅需 64 位环境时 pacman -S mingw-w64-x86_64-toolchaintoolchain 是一个元包会拉取 gcc、g、gdb、binutils 等全套编译调试工具不需要单独指定版本号。如果在 64 位系统上希望同时编译 32 位和 64 位程序可以把上面两条命令都执行——我目前的机器就是双工具链方案编 32 位 DLL 给旧系统用编 64 位主程序给新系统用。安装完成后关闭旧的 MSYS2 Shell打开对应的 MinGW-w64 Shell输入gcc -v验证安装gcc -v输出中应该能看到 gcc 版本号和 configure 配置信息如果提示命令未找到说明 PATH 没有生效检查安装目录下mingw32\bin或mingw64\bin是否正确加入环境变量或者确认你打开的是不是 MinGW-w64 开头的 Shell。提示在 MSYS2 Shell 里执行 gcc 命令通常会失败这是正常的——编译器只在 MinGW-w64 Shell 里可用。4. Qt 安装与双库方案动态库用于发布静态库用于免依赖4.1 动态库 vs 静态库许可证和发布方式的抉择在安装 Qt 之前必须先搞清楚动态库和静态库的取舍这直接影响后续发布策略。MSYS2 仓库提供两类 Qt5 包特性Qt5 动态库qt5Qt5 静态库qt5-static安装大小约 2.7GB约 2.7GB发布形态exe 数十个 dll单个 exe发布体积HelloWorld 约 10-20MB 总大小HelloWorld Release 约 11.5MB许可证要求可用 LGPL 闭源商用必须 GPL 开源许可证这条要记清楚动态 Qt 库可以用于遵循 LGPL 的商业闭源软件也可以用于 GPL 开源软件静态 Qt 库只能用于 GPL 开源软件。如果做的项目要闭源商用就别碰静态库老老实实用动态库发布虽然繁琐但不违法。如果只是自己用或者开源项目静态库一个 exe 走遍天下的体验非常爽。4.2 安装动态 Qt5 和 QtCreator在 MSYS2 Shell 里执行安装命令32 位和 64 位分别对应不同包名# 32 位系统或需要编译 32 位 Qt 程序 pacman -S mingw-w64-i686-qt5 mingw-w64-i686-qt-creator # 64 位系统 pacman -S mingw-w64-x86_64-qt5 mingw-w64-x86_64-qt-creatorQt5 开发库下载体积约 500MB安装过程比较耗时但 pacman 支持断点续传即使中途网络中断重复执行同一命令即可继续未完成的下载不会丢失已有进度。这里有个容易被误判为卡死的现象安装mingw-w64-i686-fontconfig这个包时配置过程会非常慢因为 fontconfig 要构建字体缓存不要以为 pacman 挂了耐心等待即可。另外qt5主包本身很大安装起来也慢这两个包的耗时是正常现象。装完后在 MinGW-w64 Shell 里启动 QtCreatorqtcreator 命令末尾的表示后台启动进程不占用 Shell 前台。assistant是 Qt 帮助文档浏览器designer是界面设计工具linguist是翻译工具这三个命令同样支持这种方式启动。4.3 安装静态 Qt5 并配置 Kit如果动态库还不够接着装静态库# 32 位静态 Qt5 pacman -S mingw-w64-i686-qt5-static # 64 位静态 Qt5 pacman -S mingw-w64-x86_64-qt5-static静态库包下载同样是 500MB 级别安装后占地 2.7GB 左右。装完静态库后打开 MinGW-w64 Shell 启动 QtCreator新建 Qt Widgets Application 项目在 Kit Selection 界面会看到两个套件一个是带(static)后缀的静态库套件另一个是动态库套件。我的做法是把左下角构建模式切换成 Release选择静态库套件构建矩形按钮运行。Windows 7 系统默认输出位置在C:\Users\用户名\Documents\build-hello-Desktop_Qt_static_MinGW_w64_32bit_MSYS2-Release\release\文件夹下生成的 hello.exe 大约是 11.5MB不需要任何额外 dll拷到哪都能跑。而用静态库生成 Debug 版程序则是个大坑——一个 HelloWorld 有 280MB构建耗时也长得离谱所以静态库永远配合 Release 模式使用。4.4 已知坑静态库的 QtQuick 模块 bug这里要提前说一个 MSYS2 静态 Qt 库的通病QtQuick 应用在静态库环境下运行会报模块加载失败QQmlApplicationEngine failed to load component qrc:/main.qml:2 module QtQuick.Controls is not installed qrc:/main.qml:1 module QtQuick is not installed这是 Qt 库本身的问题不是 MSYS2 打包导致的。临时解法是在 .pro 文件里显式声明 QML 模块路径或者改用动态库编译 QtQuick 项目。我的建议是凡是项目里用了 QtQuick/QML 的直接用动态库别折腾静态库这条线除非你愿意手动处理 qml 插件的静态链接。5. 扩展库安装实战qwt 与 opencv 的完整流程5.1 pacman 搜索安装方法论以 qwt 为例MSYS2 仓库里的包数量巨大不可能记住所有包名所以掌握搜索方法比死记命令更重要。安装任何扩展库第一步是更新仓库数据库pacman -Syu这条命令会把仓库元数据和系统软件包一起升级保证能找到最新版本。第二步是搜索目标包pacman -Ss qwt-Ss选项会在远程仓库中搜索包名和描述中包含 qwt 的条目。输出结果里顶头无缩进的mingw32和mingw64是软件类别代表 32 位和 64 位软件仓库类别下面带 4 个空格缩进的行是对应包的描述。例如搜索 qwt 会看到四组结果mingw32/mingw-w64-i686-qwt-qt5 6.1.0-1 Qt5 versio of the Qwt library mingw32/mingw-w64-i686-qwt-qt4 6.1.0-1 Qt4 versio of the Qwt library mingw64/mingw-w64-x86_64-qwt-qt5 6.1.0-1 Qt5 versio of the Qwt library mingw64/mingw-w64-x86_64-qwt-qt4 6.1.0-1 Qt4 versio of the Qwt library安装时只需输入完整包名不需要类别前缀也不需要末尾的版本号。装 32 位 Qt5 的 qwt 执行pacman -S mingw-w64-i686-qwt-qt564 位环境对应mingw-w64-x86_64-qwt-qt5。5.2 在 QtCreator 中使用 qwt 控件装完 qwt 后在 QtCreator 里打开一个窗体项目的*.ui文件进入设计模式把左侧控件列表拖到最底部能看到 Qwt 相关的自定义控件组直接拖到窗体上就能用。但这只是第一步项目编译还需要在.pro文件里加两行配置CONFIG qwt INCLUDEPATH /msys32/mingw32/include/qwt64 位环境把mingw32换成mingw64即可。注意 qwt 在 MSYS2 仓库里只有动态库版本所以程序发布时必须带上 qwt.dll不能期望静态链接。我的经验是qwt 控件在曲线绘制场景里比 Qt Charts 更顺手的场景是海量数据点绘制qwt 的 QwtPlotCurve 对百万级数据点的渲染性能明显优于 QtCharts。5.3 opencv 安装与 .pro 文件链接配置opencv 的安装方式和 qwt 几乎一样因为刚执行过系统升级直接搜索安装即可pacman -Ss opencv搜索结果确认包名后按架构安装# 32 位 pacman -S mingw-w64-i686-opencv # 64 位 pacman -S mingw-w64-x86_64-opencv在 Qt 项目中使用 opencv需要在 .pro 文件里链接对应的模块库。openCV 的模块划分很细下面是一份完整的模块链接配置LIBS -lopencv_calib3d \ -lopencv_contrib \ -lopencv_core \ -lopencv_features2d \ -lopencv_flann \ -lopencv_gpu \ -lopencv_highgui \ -lopencv_imgproc \ -lopencv_legacy \ -lopencv_ml \ -lopencv_nonfree \ -lopencv_objdetect \ -lopencv_ocl \ -lopencv_photo \ -lopencv_stitching \ -lopencv_superres \ -lopencv_ts \ -lopencv_video \ -lopencv_videostab \ -lopencv_viz这段配置穷举了 opencv 的所有模块实际项目里用几个链几个即可全链会显著增加编译时间。包含头文件时可以直接写#include opencv/cv.h因为 MSYS2 系统包含路径里已经配置了/msys32/mingw32/include/opencv 和 opencv2 两个文件夹都在该路径下编译器能直接找到头文件QtCreator 也会自动补全路径。opencv 同样是动态库版本所以 opencvQt 的程序必须动态发布这一点在方案设计阶段就要纳入考量——如果目标机器没装 opencv 运行库程序启动会直接报找不到 dll。6. 避坑排查MSYS2 环境下的五个血泪经验6.1 现象pacman 下载到一半卡住不动原因分析默认 SourceForge 源在国内网络环境下连接不稳定或者同时运行了多个 pacman 实例导致数据库锁。解决方法先检查是否误开了多个 MSYS2 Shell 窗口执行 pacman用pacman -Syu的升级流程覆盖下载中断的场景或者直接换镜像源。遇到unable to lock database错误删除msys64\var\lib\pacman\db.lck文件后重试。6.2 现象QtCreator 编译时报cannot find -lGL或cannot find -lpthread原因分析Windows 下 Qt 依赖的某些 Unix 语义库在 MSYS2 环境里不叫这个名字或者对应的 mingw 包装包未安装。解决方法安装mingw-w64-x86_64-gcc-libs和mingw-w64-x86_64-winpthreads两个包。另外检查.pro文件里是否多写了unix:!macx之类的条件作用域把LIBS -lpthread这样的 Unix 专属写法去掉。6.3 现象32 位和 64 位库混用链接报file is not recognized: File format not recognized原因分析在 64 位工具链下链接了 32 位库或者反过来这是 MSYS2 环境最典型的架构错配问题。解决方法确认当前打开的 Shell 是 MinGW-w64 Win64 Shell 还是 Win32 Shell用gcc -v输出里的Target:字段判断工具链架构再检查项目.pro文件里库路径是否指向了mingw32/lib而不是mingw64/lib。6.4 现象中文路径项目编译失败moc 文件生成异常原因分析MSYS2 底层的路径解析对 Unicode 支持不完善带中文的项目路径会导致 uic/moc 工具无法正确解析文件路径。解决方法项目目录、安装目录、构建目录全部使用英文和数字避免中文和空格。这是 MSYS2 生态的长期限制不要浪费时间寻找绕过方案直接规范路径。6.5 现象动态库发布的程序在新机器上提示缺少libgcc_s_seh-1.dll或libstdc-6.dll原因分析MinGW-w64 编译的程序运行时依赖 GCC 的运行时库而目标机器没有安装这些库。解决方法从msys64\mingw64\bin目录复制以下三个文件到 exe 同目录libgcc_s_seh-1.dll、libstdc-6.dll、libwinpthread-1.dll。64 位环境和 32 位环境对应的文件名略有不同32 位是libgcc_s_dw2-1.dll。或者用windeployqt工具一次性补齐所有 Qt 依赖下文详述。7. 发布环节的验证与提速windeployqt 与依赖清单核对7.1 动态库发布的标准流程动态库编译出的 Qt 程序发布是个体力活但掌握方法后可以流程化操作。编译完 Release 版 exe 后我一般按三步走第一步用 Qt 自带的 windeployqt 工具补齐基础依赖。在 MinGW-w64 Shell 里运行cd /path/to/release windeployqt hello.exe它会自动扫描 exe 的依赖从 Qt 安装目录复制所需的 Qt5Core.dll、Qt5Widgets.dll、Qt5Gui.dll 及 plugins 目录下的平台插件等到 exe 所在目录。这一步能解决大部分 Qt 基础 dll 的遗漏问题。第二步处理第三方库依赖。opencv、qwt 这类库不会被 windeployqt 识别需要手动从msys64\mingw64\bin复制对应的 dll。以 opencvQt 项目为例至少需要libopencv_core2411.dll libopencv_highgui2411.dll libopencv_imgproc2411.dll qwt.dll tbb.dll第三步验证完整性。有两条路可选用 Dependency Walker 打开 exe 查看依赖树或者直接拷贝到一台干净机器上运行让它告诉你缺什么。后者的实际效果往往更快因为 Dependency Walker 对 MSYS2 环境的 dll 解析偶尔会误报。调试 D 版发布过带 opencv 和 qwt 的 HelloWorld依赖 dll 一共 34 个总大小 58MB还要额外带上plugins\platforms里的 qwindows.dll 和 qminimal.dll总件数就到了 36 个。这就是动态库发布的代价。7.2 静态库发布的验证方法静态库这边就简单多了。Release 构建出的 hello.exe 只有 11.5MB没有任何额外 dll但编译前要确认一件事在 QtCreator 中检查当前 Kit 是不是带(static)后缀的那个构建模式是不是 Release。如果误用了静态库 Kit 编译 Debug一个 HelloWorld 能到 280MB构建时间也令人崩溃。验证静态库发布的方法把 hello.exe 复制到一台没有安装 Qt 环境的机器双击运行。能正常弹窗就说明依赖干净弹出缺少 dll 的报错说明 .pro 里可能混入了动态链接——比如CONFIG qwt这类配置会强制链接动态库静态 Qt 和动态第三方库混合使用就会出现这种情况。另外windeployqt对静态工程是多余的不要对静态 exe 执行。有一个经验无论动态还是静态发布发布前检查一遍 .pro 文件确认没有debug残留配置CONFIG release保证剥离调试符号。从那以后我每次发布前都强制走一遍「windeployqt → 第三方 dll 补齐 → 干净机器试跑」这套流程再也没有出现过发布包到客户机器上启动崩溃的黑匣子问题。这套 MSYS2 搭建方案看似绕路实际上比官网下载器更可控毕竟对开发者来说命令行就是最好的后悔药——装错了删掉重装几分钟的事。希望帮到你。本文还有配套的精品资源点击获取