Qt5.12.9 安装包这几个字，在很多做桌面端的朋友眼里基本等同于“能用、够稳、别折腾”。这套安装包装的不是一个单纯的软件，而是整套 Qt 开发环境：预编译的库、头文件、qmake 构建工具、Qt Creator 集成开发环境，以及配套的编译器与调试器。它能让你在一台干净的机器上，从零开始编译出带界面的可执行程序，并且通过自带的部署工具把依赖一并打好包，拷到别的机器上直接双击运行。适合谁来参考？三类人最典型：一是接手了老项目、必须把环境还原成 5.12.9 的维护者；二是在教学或竞赛环境里需要一套离线可复现工具链的开发者；三是刚入门、被各种“装完编译不过”的帖子劝退过的新手。下面我就按自己反复装机的实际顺序，把这个包从选型、安装、配置到排错整条链路讲透，尽量让你一次装对，少走回头路。

1. Qt5.12.9 安装包到底装了什么，先把包结构和版本定位摸清

动手点“下一步”之前，得先知道自己装的是什么。很多人卡在第一步，不是因为技术难，而是下载了一个不匹配的包，或者勾选了一堆用不上的组件，白占几十个 G。这一节把版本定位、包类型和内部构成拆开讲，后面所有操作都建立在这个认知上。

1.1 为什么到现在还有人在装这个版本

Qt 5.12 系列是长期支持分支，5.12.9 是这个分支收官阶段的补丁版本，发布于 2020 年底。它的意义不在于“新”，而在于“冻结”——API 稳定、行为可预期、生态里绝大多数第三方库都验证过。我手上有个图像处理类的小工具，从 5.9 一路迁到 5.12.9 之后再没动过，原因是这个版本的 Qt Widgets 渲染行为、高 DPI 缩放策略、QSS 样式解析都定型了，界面不会因为升级突然错位。

再一个现实原因：预编译套件覆盖面广。5.12.9 同时提供 MinGW 7.3.0 的 32/64 位、MSVC 2015 与 MSVC 2017 的 32/64 位，还有 Android 的几套 ABI。这种“一个安装器装齐所有目标平台”的便利，在后来的版本里逐步被拆散或淘汰（32 位预编译套件越来越少）。如果你需要出 32 位 Windows 程序，5.12.9 是很省心的选择。

还有一点容易被忽略：它的运行库依赖相对保守，对 Windows 7 SP1 仍然友好。做工业上位机、内网工具的朋友，目标机可能就是老系统，新版本 Qt 直接不支持了，只能往回退。

注意：长期支持不等于永久支持。选这个版本要接受它不再有新特性、部分新硬件加速路径不支持的事实，把它当“稳定基线”而不是“技术前沿”。

1.2 在线安装器、离线包、源码包，三种包别选错

这一步是踩坑重灾区。官方提供的安装介质至少有三种形态，用途完全不同：

在线安装器的好处是灵活，坏处是它依赖网络，中途断线会留下半残的安装目录；而且老版本的仓库路径有时会被调整，导致“明明有网却拉不到 5.12.9”。离线包反过来，体积大但一次到位，装机房里拷 U 盘就行，我做批量部署时一律用离线包。

源码包这一项要特别提醒：它不是“更完整的安装包”，而是“原材料”。编译一套完整的 Qt 5.12.9，配置好的机器也要一两个小时，还要先装 Python、Perl 等前置工具。除非你要裁剪模块或者改 Qt 自身的源码，否则别碰。

提示：不确定自己该用哪种，就先想清楚一件事——目标机器能不能稳定联网。能，用在线安装器；不能，或者要装多台，用离线包。这个判断做完，后面就顺了。

2. 安装前的准备工作与安装包获取要点

我见过太多“装到 80% 报错”的案例，回头查原因，八成是准备工作没做。磁盘、路径、权限、校验这四件事花十分钟搞定，能省掉后面两小时的折腾。

2.1 磁盘、路径与权限的三条硬规矩

第一条，磁盘空间要留够。单个预编译套件装完大概 1.2 GB 上下，Qt Creator 加工具链再占 1 GB 左右，如果你勾了多个套件加源码加 WebEngine，整体能到 8 至 10 GB。安装过程还需要临时空间解压，所以目标盘至少留 20 GB 余量，别卡在最后一步“磁盘空间不足”上。

第二条，路径绝对不能含中文和空格。这不是 Qt 独有的毛病，而是整条工具链的通病：qmake 生成的 Makefile 里路径不做转义、部分编译器的中间文件处理对空格不友好、第三方脚本拼接命令行时直接崩。我一般统一用D:\Qt\Qt5.12.9这种短、纯英文、无空格的路径。特别注意别装到C:\Program Files下面，那个目录有 UAC 保护，编译时写中间文件会随机失败，症状是“有时候能编过有时候不能”，极难排查。

第三条，权限。Windows 上启动安装器时右键“以管理员身份运行”，尤其是装到 D 盘根目录之外的系统盘位置。安装器需要写注册表项（关联文件类型、登记卸载信息），权限不足会在结束阶段报一个看不懂的错误码。

注意：安装路径选定后不要再改。Qt 的部分配置文件里写的是绝对路径，手动移动目录会导致 Kit 失效、qmake 找不到库。要换位置就老老实实重装或者用维护工具迁移。

2.2 下载渠道与完整性校验

渠道方面，优先走官方发布页；国内网络环境下如果速度不理想，可以用几个公共的开源镜像站做加速，注意镜像站的目录结构通常和官方一致，找qt/official_releases/qt/5.12/5.12.9/这样的层级就行。用镜像时有个细节：一定要确认镜像同步的是完整文件，有些镜像只同步了部分子目录，下下来的安装器体积明显偏小，那就是没同步完。

校验这一步很多人跳过，我建议别跳。安装包动辄几个 G，传输中断导致文件尾部损坏是很常见的，表现是安装器双击没反应，或者解压到一半报 CRC 错误。做法很简单：比对官方页面上给出的哈希值，本地用系统自带的哈希计算命令算一遍。以 Windows 为例：

certutil -hashfile qt-opensource-windows-x86-5.12.9.exe SHA256

输出的哈希和官方公布的完全一致再用。Linux 下就是sha256sum 文件名。多花三十秒，避免后面怀疑人生。

另外补一句环境依赖：MSVC 套件必须搭配对应版本的 C++ 编译器才能用，也就是说机器上得先装好带“使用 C++ 的桌面开发”工作负载的 Visual Studio（2017 或 2019 均可，因为二者二进制兼容）。MinGW 套件则自带编译器，装完即用，适合机器上什么开发环境都没有的干净系统。这个选择会直接影响你后面勾组件，先在脑子里定下来。

3. 安装过程逐屏拆解与组件勾选策略

真正点下去的环节，多数人出错不在“不会点”，而在“勾多了”或“勾少了”。这一节按向导顺序走一遍，重点讲每个决策点的判断依据。

3.1 安装向导每一步该点什么

启动安装器后，第一屏是欢迎页，直接下一步。第二屏要求登录账号，这一步可以直接跳过——跳过不影响安装，只是不能提交反馈。第三屏是许可协议，勾选接受继续。

第四屏是安装目录，这里有个容易误解的地方：你选的路径是“安装根目录”，安装器会在它下面自动建一层版本号目录。比如你选D:\Qt\Qt5.12.9，最终套件实际落在D:\Qt\Qt5.12.9\5.12.9\msvc2017_64。所以别自己在路径里再手写一遍版本号，会变成两层嵌套，看着难受还容易在配环境变量时写错。

第五屏是组件选择树，这是全场最关键的一屏，下一小节单独展开。第六屏是许可协议确认（部分组件有独立协议），第七屏开始下载安装，最后一屏是完成页，建议勾上“启动 Qt Creator”，顺手验证一下能否正常打开。

安装耗时取决于勾选量，单套件加工具大约十几分钟，全勾能到一小时以上。中途别点取消，取消后残留目录需要手动清，很多人重装失败就是因为旧目录没删干净。

3.2 组件清单：哪些必选，哪些纯占地方

组件树分三大块：Qt 版本下的预编译套件、Tools 工具、以及 Sources 源码。我按“必选 / 按需 / 基本不用”三档给个参考，你可以对照自己情况微调：

举两个具体场景。场景一：你只是要学 Qt，写写界面练手，那就只勾 MinGW 7.3.0 64-bit 加 Qt Creator 加 Tools 里的 MinGW，装完体积约 2 GB，干净清爽。场景二：公司项目要发给客户，需要 MSVC 发布版，那就勾 MSVC 2017 64-bit，同时机器上装好 VS 2017 或 2019 的 C++ 工作负载。

提示：WebEngine 这一项要格外克制。它内含一整套浏览器内核，单个组件好几 GB，编译链接时间显著拉长，而且和 MinGW 套件不兼容。如果你的需求只是“显示一段网页”，先评估能不能用系统浏览器外链或者轻量方案替代。

还有个小技巧：组件树底部有个“Archive”或“旧版本”勾选项，勾上后会展开历史版本。如果你需要同时装 5.12.9 和更老的版本（比如为了复现某个老项目），一次性在同一安装器里勾好，比装两个独立安装器干净得多，因为它们共享同一个 Tools 目录。

3.3 MSVC 与 MinGW 怎么选才不打架

这是新手最纠结的问题，我把实际差异列成表，你按项目性质对号入座：

我的实际做法是两套都装，日常写代码用 MinGW 快速迭代，正式出包用 MSVC。但要注意一个坑：同一个工程不要在两个套件之间来回切而不清理构建目录，中间文件里的编译选项会残留，导致链接阶段报一堆符号找不到。切换套件时养成先“清理项目”再“执行 qmake”的习惯。

还有一个隐蔽问题：MSVC 套件要求编译器版本与套件 ABI 匹配。Qt 5.12.9 的 MSVC 2017 预编译库，用 VS 2019 编译是安全的（二进制兼容），但用 VS 2015 编译就会链接出错。反过来，MSVC 2015 套件用 VS 2017 编译也可能出问题。记住原则：套件版本 ≤ 实际编译器版本，且二者同属一个兼容世代。

4. 装完不算完，环境变量、Kit 与第一次编译验证

安装进度条走完只是“文件到位”，能不能编译还是另一回事。这一段是把文件变成可用工具链的关键。

4.1 环境变量的加与不加

网上教程几乎都会让你把C:\Qt\...\bin加到系统 PATH 里，我的建议是：能不全局加就不加。原因是 Qt 的bin目录里有 qmake、windeployqt、以及一堆 DLL，一旦 PATH 里存在多个 Qt 版本的 bin，命令行里敲qmake到底用的是哪个就变成玄学，症状是“明明改了代码，编译出来还是旧行为”。

那命令行构建怎么办？用临时会话级的 PATH。开一个命令行窗口，执行：

set PATH=D:\Qt\Qt5.12.9\5.12.9\msvc2017_64\bin;%PATH% qmake -v

第二条命令的输出必须是这样的形式：

QMake version 3.1 Using Qt version 5.12.9 in D:/Qt/Qt5.12.9/5.12.9/msvc2017_64/lib

版本号和路径都对上，说明环境生效了。如果输出的是别的版本，那就是 PATH 里还有别的 Qt 抢在前面，用where qmake查一下排在前面的那个是谁，把它从 PATH 里挪走。

Qt Creator 内部不需要依赖系统 PATH，它通过 Kit 里的绝对路径调用 qmake，这也是我推荐用 Kit 而不是全局环境变量的原因——项目之间互不干扰。

4.2 Qt Creator 里 Kit 的配置细节

打开 Qt Creator，进“工具 - 选项 - 构建和运行”，这里有三个标签页要依次检查：Qt Versions、编译器、构建套件（Kit）。

Qt Versions 页签，点“添加”，浏览到D:\Qt\Qt5.12.9\5.12.9\msvc2017_64\bin\qmake.exe，选中后它会自动识别出版本号 5.12.9。如果识别成“未知版本”，八成是路径选错了或者文件损坏。

编译器页签，MinGW 套件通常会被自动登记（因为它就在 Qt 安装目录里）；MSVC 需要手动添加，路径指向 VS 安装目录下的cl.exe，一般会自动扫描到。如果列表里空空如也，说明 VS 的 C++ 工作负载没装，回去补装。

构建套件页签，新建一个 Kit，把三项对上：设备类型选桌面、编译器选对应套件、Qt 版本选刚才登记的 5.12.9。调试器那一栏，MinGW 选套件自带的 GDB，MSVC 需要 Windows SDK 里的调试工具（CDB），没装的话调试功能会灰掉，但编译不受影响。

配好后可以用 Kit 页面上的“Make Default”把它设为默认，新建项目时就自动选中了。

4.3 用 .pro 和 CMake 各跑一遍最小工程

验证环境最直接的办法是写个最小程序跑通。先看 qmake 路线，新建一个纯文本文件命名为hello.pro：

QT += core gui widgets CONFIG += c++11 TARGET = hello TEMPLATE = app SOURCES += main.cpp

同目录下写main.cpp：

#include <QApplication> #include <QLabel> int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label("Qt 5.12.9 环境验证通过"); label.resize(320, 120); label.show(); return app.exec(); }

命令行里依次执行qmake hello.pro、mingw32-make（MinGW 套件是mingw32-make，MSVC 套件是nmake）。生成hello.exe后直接运行，看到窗口就说明整条链路通了。

再看 CMake 路线，现在越来越多的工程用 CMake 管理，Qt 5.12.9 的 CMake 支持已经很完整。写一个CMakeLists.txt：

cmake_minimum_required(VERSION 3.5) project(hello LANGUAGES CXX) set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTOUIC ON) set(CMAKE_AUTORCC ON) find_package(Qt5 5.12.9 REQUIRED COMPONENTS Core Gui Widgets) add_executable(hello main.cpp) target_link_libraries(hello PRIVATE Qt5::Core Qt5::Gui Qt5::Widgets)

构建时把CMAKE_PREFIX_PATH指向套件目录，这样 CMake 才能找到 Qt 的配置文件：

cmake -S . -B build -G "MinGW Makefiles" -DCMAKE_PREFIX_PATH=D:/Qt/Qt5.12.9/5.12.9/mingw73_64 cmake --build build

两个路线都跑通，说明安装、编译器、构建工具全部就位。这一步别嫌麻烦，它能把后面 90% 的“编译不过”提前暴露在可控环境里。

5. 程序发布与依赖打包

开发环境跑通只完成一半，真正交付时你会发现 exe 拷到别的机器上打不开，提示缺 DLL。这一节讲怎么用自带工具把依赖收齐。

5.1 windeployqt 的正确用法

Qt 自带一个部署工具，原理是扫描你的 exe，把运行时需要的 Qt 动态库、平台插件、以及编译器运行库一并拷到同目录。基本用法是先建一个空目录，把 exe 拷进去，然后执行：

windeployqt --release --no-translations --no-opengl-sw D:\dist\hello.exe

几个参数值得说明。--release明确按发布版规则收集（自动跳过带 d 后缀的调试库），不加这参数在混合构建目录里容易抓错库；--no-translations跳过几十种语言包，体积能减十几 MB，国内单语环境下没人用得上；--no-opengl-sw跳过软件渲染的 OpenGL 兼容库，除非目标机器是老旧集成显卡且你用到了 3D 相关功能，否则不需要。

如果是 QML 项目，还要加--qmldir指向你的 QML 源码目录，让它扫描实际用到的模块：

windeployqt --release --qmldir D:\project\qml D:\dist\app.exe

跑完检查一下目录，应该能看到platforms\qwindows.dll、Qt5Core.dll、Qt5Gui.dll、Qt5Widgets.dll这些。少了platforms目录，程序启动时会报“无法加载平台插件 windows”，这是最典型的部署遗漏。

5.2 发布目录的几个常见坑

第一个坑是编译器运行库。MSVC 编译的程序依赖vcruntime140.dll和msvcp140.dll，windeployqt在多数情况下会帮你拷，但不保证每次都有。稳妥的做法是随包附带 VC 运行库安装程序，或者直接确认目标机上已装。MinGW 编译的程序依赖libgcc_s_seh-1.dll、libstdc++-6.dll、libwinpthread-1.dll，这三个windeployqt会处理，但要确认位数一致。

第二个坑是位数混用。32 位 exe 配 64 位 DLL，症状是“不是有效的 Win32 应用程序”，一眼能看出来；但反过来 64 位 exe 配了 32 位 DLL，报的是更含糊的加载失败，容易绕弯路。发布前统一用同一个套件构建，别东拼西凑。

第三个坑是调试版误发。调试版 exe 依赖带 d 后缀的库，体积大、性能差，而且调试库的授权条款不允许随意分发。发布前一定确认构建配置是 Release，windeployqt也带--release。我习惯在构建完看一眼 exe 体积，Hello World 级别的界面程序，Release 版几百 KB，Debug 版能到好几 MB，用体积做快速判断很有效。

注意：部署目录里不要保留源码和中间文件，.obj、.pdb（除非要保留符号）、Makefile这些东西一起打包，既增大体积又暴露工程结构。

6. 常见问题排查速查表与踩坑实录

下面这些是我在不同机器、不同系统上实际撞过的，按发生阶段归类，方便对照。

6.1 安装阶段的问题

安装阶段的报错信息普遍不友好，经常只给一个错误码。这时候别急着搜错误码，先做三件事：看路径有没有中文空格、看杀毒软件有没有拦截安装器的写文件行为、看磁盘剩余空间。这三条覆盖了绝大多数安装失败。杀软拦截这一点尤其隐蔽，它不弹窗提示，只是默默把某个 DLL 隔离掉，表现是装成功了但一编译就报找不到文件。

6.2 编译与运行阶段的问题

“Cannot find file: xxx.pro” —— 通常是命令行没有cd到工程目录，或者.pro文件名拼错。qmake 的参数是相对当前目录解析的，路径里带空格时还要加引号。

“Project ERROR: Unknown module(s) in QT: xxx” —— 你引用的模块在当前套件里没装。最常见的是写了QT += webenginewidgets却只装了 MinGW 套件，而 WebEngine 在 Windows 上只有 MSVC 2017 64 位提供。解决办法是换套件或者删掉对该模块的依赖。

“LNK2019: 无法解析的外部符号” —— 三种可能：一是.pro里漏了QT +=对应模块；二是切换过套件但构建目录没清理，中间文件里残留旧配置；三是函数声明有但实现没参与编译（忘加进 SOURCES）。按顺序排查，先清理再 qmake 是成本最低的一步。

“无法定位程序输入点于动态链接库” —— 运行时的 DLL 和编译时的库版本不一致。多见于机器上装了多个 Qt，PATH 里第一个命中的是别的版本。把目标目录的 Qt DLL 拷到 exe 同目录，或者清理 PATH 后重试。

“This application failed to start because no Qt platform plugin could be initialized” —— 部署时漏了platforms目录，或者目录在但里面是空壳。重新跑一遍windeployqt即可。

“编译通过但界面在高分屏上糊成一片” —— 5.12 的高 DPI 缩放默认策略偏保守。可以在main函数里QApplication构造之前设置缩放属性，或者调整环境变量。这个问题没有一键解，建议先在小窗口上验证效果再全局应用。

提示：遇到编译错误，先看输出的第一行错误，而不是最后一行。链接错误往往最后一行是“collect2: ld returned 1 exit status”这种总结性的，真正原因在上面几十行。

6.3 多版本共存与后续维护

机器上需要同时存在多个 Qt 版本是很常见的。正确姿势是：所有版本装在同一根目录下（比如都在D:\Qt），安装器会按版本号建子目录，互不覆盖。Qt Creator 里为每个版本各建一个 Kit，项目属性里切换 Kit 即可，不需要动环境变量。

想增删组件，运行安装根目录下的维护工具（MaintenanceTool），它复用安装器界面，可以补勾或取消勾选，卸载单个套件而不影响其他。这一点比手动删目录安全得多，手动删会留下注册表项和文件关联，后面重装可能报“已存在安装”。

彻底清理时有个顺序：先用维护工具卸载组件，再卸载整个安装，最后手动删除残留的根目录。Windows 上还要检查用户目录下的配置残留（Qt Creator 的配置和缓存），这部分不清，重装后可能带着上次的错误 Kit 配置。

在 Linux 上安装的流程和 Windows 差异不大，只是安装介质是可执行的.run文件，需要先chmod +x再执行。Linux 下多版本共存的习惯做法是用版本切换工具在qmake的可执行文件之间做软链，或者干脆全部走 Kit 配置，不依赖系统级的命令。

最后分享一个我用了几年的小习惯：每次装完环境，把关键路径、套件名、编译器版本、验证命令的输出，记在一个纯文本文件里放在工程根目录。半年后回来接手，或者换机器重装，照着这份记录十分钟就能复现，比翻聊天记录可靠得多。这套 5.12.9 的环境我前后装过不下二十次，真正花时间的从来不是安装本身，而是“记不清上次到底勾了哪些”。