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 在线安装器、离线包、源码包三种包别选错这一步是踩坑重灾区。官方提供的安装介质至少有三种形态用途完全不同包类型典型体积特点适用场景在线安装器二三十 MB启动后联网拉取组件可自由勾选网络通畅、需要精确控制组件离线安装包三到四 GB内含全部预编译套件一次装完内网、装机房、需要可复现源码包五百 MB 上下需要自己 configure 并编译定制裁剪、交叉编译、改库源码在线安装器的好处是灵活坏处是它依赖网络中途断线会留下半残的安装目录而且老版本的仓库路径有时会被调整导致“明明有网却拉不到 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 Studio2017 或 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 源码。我按“必选 / 按需 / 基本不用”三档给个参考你可以对照自己情况微调组件建议说明MinGW 7.3.0 64-bit必选新手首选自带编译器与 GDB装完立即可编译MSVC 2017 64-bit必选做正式发布性能好、调试器成熟需外部装 VSMinGW 7.3.0 32-bit按需需要出 32 位程序时才勾MSVC 2015 32/64-bit按需老项目兼容新项目不必Qt WebEngine按需只有 MSVC 2017 64 位有预编译体积巨大Android 各 ABI按需需另配 JDK 与 NDK纯桌面开发别勾Sources按需只有要读源码或自行编译时才需要Qt Creator必选集成开发环境本体MinGW 7.3.0Tools 里那项必选与套件配套的编译器发行版Qt Debug Information Files可跳过仅在做 Qt 自身崩溃分析时有用举两个具体场景。场景一你只是要学 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 7.3.0MSVC 2017前置依赖无自带需装 VS 的 C 桌面开发负载编译速度中等较快生成程序体积偏大偏小调试体验GDB够用但界面信息少CDB断点与调用栈信息更完整与第三方库兼容部分预编译库只提供 MSVC 版本生态主流兼容性最好32 位支持有有我的实际做法是两套都装日常写代码用 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 PATHD:\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 选套件自带的 GDBMSVC 需要 Windows SDK 里的调试工具CDB没装的话调试功能会灰掉但编译不受影响。配好后可以用 Kit 页面上的“Make Default”把它设为默认新建项目时就自动选中了。4.3 用 .pro 和 CMake 各跑一遍最小工程验证环境最直接的办法是写个最小程序跑通。先看 qmake 路线新建一个纯文本文件命名为hello.proQT core gui widgets CONFIG c11 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-makeMinGW 套件是mingw32-makeMSVC 套件是nmake。生成hello.exe后直接运行看到窗口就说明整条链路通了。再看 CMake 路线现在越来越多的工程用 CMake 管理Qt 5.12.9 的 CMake 支持已经很完整。写一个CMakeLists.txtcmake_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_PATHD:/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.dllwindeployqt在多数情况下会帮你拷但不保证每次都有。稳妥的做法是随包附带 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 后缀的库体积大、性能差而且调试库的授权条款不允许随意分发。发布前一定确认构建配置是 Releasewindeployqt也带--release。我习惯在构建完看一眼 exe 体积Hello World 级别的界面程序Release 版几百 KBDebug 版能到好几 MB用体积做快速判断很有效。注意部署目录里不要保留源码和中间文件.obj、.pdb除非要保留符号、Makefile这些东西一起打包既增大体积又暴露工程结构。6. 常见问题排查速查表与踩坑实录下面这些是我在不同机器、不同系统上实际撞过的按发生阶段归类方便对照。6.1 安装阶段的问题现象根因处理方式安装器双击无反应安装包下载不完整重新校验哈希后重下卡在“正在获取”页面网络拉取组件失败换离线包或换镜像源安装到 90% 报错回滚目标路径含中文或权限不足换纯英文短路径以管理员运行组件列表里没有 5.12.9安装器未勾选旧版本显示勾上 Archive 选项刷新列表装完体积远小于预期勾选组件少或中途取消用维护工具补装安装阶段的报错信息普遍不友好经常只给一个错误码。这时候别急着搜错误码先做三件事看路径有没有中文空格、看杀毒软件有没有拦截安装器的写文件行为、看磁盘剩余空间。这三条覆盖了绝大多数安装失败。杀软拦截这一点尤其隐蔽它不弹窗提示只是默默把某个 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 和编译时的库版本不一致。多见于机器上装了多个 QtPATH 里第一个命中的是别的版本。把目标目录的 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 的环境我前后装过不下二十次真正花时间的从来不是安装本身而是“记不清上次到底勾了哪些”。 
长河君 · 2026/10/24 7:51:13 · 阅读 1.2k Qt5.12.9安装包安装配置与依赖打包完整指南
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 在线安装器、离线包、源码包三种包别选错这一步是踩坑重灾区。官方提供的安装介质至少有三种形态用途完全不同包类型典型体积特点适用场景在线安装器二三十 MB启动后联网拉取组件可自由勾选网络通畅、需要精确控制组件离线安装包三到四 GB内含全部预编译套件一次装完内网、装机房、需要可复现源码包五百 MB 上下需要自己 configure 并编译定制裁剪、交叉编译、改库源码在线安装器的好处是灵活坏处是它依赖网络中途断线会留下半残的安装目录而且老版本的仓库路径有时会被调整导致“明明有网却拉不到 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 Studio2017 或 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 源码。我按“必选 / 按需 / 基本不用”三档给个参考你可以对照自己情况微调组件建议说明MinGW 7.3.0 64-bit必选新手首选自带编译器与 GDB装完立即可编译MSVC 2017 64-bit必选做正式发布性能好、调试器成熟需外部装 VSMinGW 7.3.0 32-bit按需需要出 32 位程序时才勾MSVC 2015 32/64-bit按需老项目兼容新项目不必Qt WebEngine按需只有 MSVC 2017 64 位有预编译体积巨大Android 各 ABI按需需另配 JDK 与 NDK纯桌面开发别勾Sources按需只有要读源码或自行编译时才需要Qt Creator必选集成开发环境本体MinGW 7.3.0Tools 里那项必选与套件配套的编译器发行版Qt Debug Information Files可跳过仅在做 Qt 自身崩溃分析时有用举两个具体场景。场景一你只是要学 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 7.3.0MSVC 2017前置依赖无自带需装 VS 的 C 桌面开发负载编译速度中等较快生成程序体积偏大偏小调试体验GDB够用但界面信息少CDB断点与调用栈信息更完整与第三方库兼容部分预编译库只提供 MSVC 版本生态主流兼容性最好32 位支持有有我的实际做法是两套都装日常写代码用 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 PATHD:\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 选套件自带的 GDBMSVC 需要 Windows SDK 里的调试工具CDB没装的话调试功能会灰掉但编译不受影响。配好后可以用 Kit 页面上的“Make Default”把它设为默认新建项目时就自动选中了。4.3 用 .pro 和 CMake 各跑一遍最小工程验证环境最直接的办法是写个最小程序跑通。先看 qmake 路线新建一个纯文本文件命名为hello.proQT core gui widgets CONFIG c11 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-makeMinGW 套件是mingw32-makeMSVC 套件是nmake。生成hello.exe后直接运行看到窗口就说明整条链路通了。再看 CMake 路线现在越来越多的工程用 CMake 管理Qt 5.12.9 的 CMake 支持已经很完整。写一个CMakeLists.txtcmake_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_PATHD:/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.dllwindeployqt在多数情况下会帮你拷但不保证每次都有。稳妥的做法是随包附带 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 后缀的库体积大、性能差而且调试库的授权条款不允许随意分发。发布前一定确认构建配置是 Releasewindeployqt也带--release。我习惯在构建完看一眼 exe 体积Hello World 级别的界面程序Release 版几百 KBDebug 版能到好几 MB用体积做快速判断很有效。注意部署目录里不要保留源码和中间文件.obj、.pdb除非要保留符号、Makefile这些东西一起打包既增大体积又暴露工程结构。6. 常见问题排查速查表与踩坑实录下面这些是我在不同机器、不同系统上实际撞过的按发生阶段归类方便对照。6.1 安装阶段的问题现象根因处理方式安装器双击无反应安装包下载不完整重新校验哈希后重下卡在“正在获取”页面网络拉取组件失败换离线包或换镜像源安装到 90% 报错回滚目标路径含中文或权限不足换纯英文短路径以管理员运行组件列表里没有 5.12.9安装器未勾选旧版本显示勾上 Archive 选项刷新列表装完体积远小于预期勾选组件少或中途取消用维护工具补装安装阶段的报错信息普遍不友好经常只给一个错误码。这时候别急着搜错误码先做三件事看路径有没有中文空格、看杀毒软件有没有拦截安装器的写文件行为、看磁盘剩余空间。这三条覆盖了绝大多数安装失败。杀软拦截这一点尤其隐蔽它不弹窗提示只是默默把某个 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 和编译时的库版本不一致。多见于机器上装了多个 QtPATH 里第一个命中的是别的版本。把目标目录的 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 的环境我前后装过不下二十次真正花时间的从来不是安装本身而是“记不清上次到底勾了哪些”。