从 4.x 一路装到 6.x，Windows、Ubuntu 全折腾过。很多人在 Qt 上写代码没问题，卡死在第一步安装上：版本选错、编译器没装、PATH 没配好，最后冒出那句经典的 "could not find the Qt platform plugin 'windows'" 就开始怀疑人生。这篇文章我按实际的安装顺序整一套完整流程，版本怎么选、下载源走哪条、装完怎么验证、报错怎么查，你跟着走一遍，环境基本上一天内就能跑起来。
1. 安装前的准备：先想明白装给谁用、怎么用
1.1 搞清楚你要哪个版本的 Qt
Qt 的版本号看着像流水线，其实选择逻辑很固定。目前个人项目里最常听到的是 5.12、5.14.2、5.15.2 和 6.x 这一堆。如果公司项目或参考代码还在用旧版，别盲目追新——我记得很清楚，Qt 5.15 是最后一个提供开源离线安装包的长期支持版本，很多教学帖、老工程的依赖都停在这附近。新学的人我更建议直接上 Qt 6 的 LTS，或者稳妥的 5.15.2，前者的新特性多，后者的资料全。
判断标准其实就三条：第一，项目目标平台和编译器是什么；第二，依赖的库有没有版本绑定；第三，团队里别人用什么。比如你后面想接 Halcon 做图像处理，Halcon 的算子接口和编译器版本匹配很重要，这种情况下就得提前确认 Qt 的位数、编译器类型和 Halcon 的运行时要求能对上。
另外位数问题别忽略。32 位和 64 位的程序对应不同构建目录，第三方库（比如工业相机 SDK、数据库驱动）通常也分 x86/x64，装之前一定要想清楚主攻哪个。现在新机器基本都是 64 位，直接选 64 位 Kit 最省事，但有些老设备或串口控件只提供 32 位库，那就得老老实实保留一个 32 位环境。
1.2 离线安装包和在线安装器选哪个
很多人不知道 Qt 的安装器分两种。在线安装器就是那个需要登录账号、边下边装的 MaintenanceTool 套件，优势是可以按需勾选组件、随时增减，缺点是网络不稳定时很容易中断，而且新版要求注册账号。离线安装包则是一个完整的 .exe 或 .run 文件，体积大，但装的时候不需要联网，也不会出现"下载到一半断了"的尴尬。
我的建议很直接：能用离线包就别用在线安装器。尤其是国内网络环境，几 GB 的离线包用镜像源一口气拉下来，比在线安装器逐组件下载靠谱得多。Qt 5.15.2 之前的老版本都有现成的离线包，找对镜像十分钟就能下完。Qt 6 之后的离线包没那么好找了，官方在线安装器成了事实上的标准路径，不过清华镜像等源里也保留了离线包，后面详细说。
1.3 MSVC 和 MinGW 系到底差在哪
这是新手最容易晕的地方。Qt 在 Windows 上有两套编译工具链：MSVC 用的是微软 Visual Studio 的编译器，MinGW 用的是 GNU 社区在 Windows 上的移植编译环境。"qt-qpa-plugin 找不到"、依赖库链接失败、第三方库调不通，很多问题的根源都是两套工具链混用。
选 MSVC 还是 MinGW，核心看两个场景。如果你的开发流程里用 Visual Studio、需要调试 Windows 原生 API、或者要对接工业库比如 Halcon，那 MSVC 是必然选择，注意你机器上还得装对应版本的 Visual Studio Build Tools。如果只是想快速做界面工具、不依赖太多第三方原生库，MinGW 更省事，因为它的路径和环境变量配置更简单，Qt 安装包里自带编译器，不用额外装 VS。
我个人在 Windows 上主力是 msvc2019_64，原因就是做图像处理和工业软件时，MSVC 生态的兼容性更稳。但你如果是刚开始入门，别两头纠结，先选一个用起来，后面有跨编译器需求再补。
2. 下载渠道：官方源和清华镜像怎么搭着用
2.1 官方下载路径的正确打开方式
Qt 官方网站的下载入口藏得比较深，直接从主页找"Downloads"容易点到营销页。真正有效的是直接进 download.qt.io 或 archive.qt.io 的目录结构，里面按版本、按平台分类全套安装包。老版本离线包都在 archive 路径下，新版本在线安装器在官方下载页或者镜像源的 online_installers 目录里。
需要注意，官方域名的在线安装器没有账号是跑不动的，这是 2020 年之后许可证策略调整的结果。开源用户选 open source 对应的安装器就行，但依然要有 Qt 账户。不想注册账号的话，就去镜像站找 offline 安装包。
2.2 清华镜像源的配置细节
国内拉 Qt 离线包，清华 TUNA 镜像基本是首选，地址是 mirrors.tuna.tsinghua.edu.cn/qt/。目录结构和官方 archive 基本一致，老版本的文件都在那边留了一份。下载时直接定位到对应版本目录：
- Windows 平台找 qt-opensource-windows-x86-5.15.2.exe 这类命名
- 新版本找 qt-opensource-xxx-online-installer 或 archive 里的离线包
- Linux 找 qt-opensource-linux-x64-5.14.2.run
用浏览器下载容易断，我习惯用支持断点续传的下载工具拉镜像文件。几 GB 的包一旦中途断了重头再来，时间成本扛不住。
2.3 文件完整性怎么验证
下载完第一件事不是双击安装，而是校验文件完整性。Qt 官方和镜像站都提供对应的 .md5 或 .sha1 校验文件。Windows 上可以用 certutil -hashfile 命令，PowerShell 里的 Get-FileHash 也行。比如校验 5.15.2 的安装包：
Get-FileHash .\qt-opensource-windows-x86-5.15.2.exe -Algorithm SHA1拿产出的哈希值和镜像站标注的对比，一致就说明文件没损坏。这一步很多人跳过，但一旦遇到安装器解压失败、装到一半报错，回头排查时你会感谢当时多花的一分钟。
3. Windows 下的完整安装流程
3.1 动手前必须先处理的三个前置条件
第一，安装路径。千万别装到带中文、空格或特殊符号的路径下，比如 C:\Program Files\Qt 这种带空格的路径也尽量避开。Qt 的构建系统对路径敏感，后续 Makefile 和编译器工具链一旦碰上空格，报错能把人绕晕。我一般装到 D:\Qt\ 这种纯英文路径，清爽且无后续烦恼。
第二，MSVC 用户先检查有没有装 Visual Studio 的 Build Tools。如果选的是 msvc2019_64 组件，机器上必须得有 VS2019 对应的 C++ 开发环境，具体是 MSVC v142 编译工具链和 Windows SDK。没有的话，Qt 装完了也无法编译，因为 Qt 本身不捆绑微软编译器。
第三，管理员权限。别直接右键"以管理员身份运行"走完全程，Qt 的目录写入不需要全局管理员，但安装过程中要改环境变量、注册系统组件时，权限不足会静默失败。稳妥的做法是右键安装包选择管理员运行，路径选用户可写的位置。
3.2 安装向导里每一步怎么勾
双击安装包后，第一屏是欢迎页，第二屏选组件。很多新手在这里全选，结果装出十几个 GB 还慢得不行。正确的勾法是你的编码需求：
- Qt 5.15.2 里至少勾选 Qt 5.15.2 下的 msvc2019_64 或 mingw81_64
- 如果调试需要，再勾选 Sources 源码包，体积大但看源码排错很有用
- Qt Creator 组件在 Tools 分类下，默认勾选，别去掉
- 不需要的模块如 Android、WebAssembly 组件，等你真用到再来回折腾不迟
另外有个很容易被忽略的细节是"Qt Debug Information Files"这类调试符号文件，勾上之后崩溃调试的时候能看到调用栈里的行号和模块信息，对排查 Qt 自身的崩溃问题帮助非常大。磁盘空间能接受的话建议勾上。
组件选完就是漫长的复制等待。安装完成后，工具菜单里会生成 Qt Creator 和 MaintenanceTool 的快捷方式。先别急着打开，下一步是配置编译器套件。
3.3 Qt Creator 里编译器套件不报红的配置
第一次打开 Qt Creator，它会自动扫描本机的编译器和调试器。打开"工具-选项-Kits"，正常情况下能看到一个默认 Kit，比如 Desktop Qt 5.15.2 MSVC2019 64bit。关键看三点：编译器栏是否显示 Microsoft Visual C++ Compiler，调试器栏是否自动识别 CDB，Qt 版本栏是否指向你刚安装的 qmake 路径。
如果 Kit 显示黄色感叹号或红色错误，原因基本是编译器没被识别。MSVC 的编译器信息需要从 Windows 注册表读取，如果系统里只有精简版 VS 组件，Qt Creator 可能扫不到。解决办法是打开 Visual Studio Installer，补装"使用 C++ 的桌面开发"工作负载，然后重启 Qt Creator 重新扫描。
MinGW 用户相对简单，安装包自带编译器，Kit 一般自动匹配。但我通常会手动确认一下构建目录用的是 64 位版本，避免出现"64 位 Qt 配 32 位 MinGW"这类默认配置的坑。
3.4 环境变量 PATH 的正确配置
Qt 安装完，默认的安装器会往系统 PATH 里加一行 Qt 的 bin 路径。但我见过不少机器装完没有自动加，或者加的是临时解压路径，这就会导致运行程序时出现 "could not find the Qt platform plugin 'windows'"。
正确做法是手动确认一下。右键"此电脑-属性-高级系统设置-环境变量"，在系统变量 PATH 里添加你的 Qt bin 目录，比如 D:\Qt\5.15.2\msvc2019_64\bin，同时把编译器对应的 DLL 目录（比如 VS 的 VC\Tools\MSVC\版本\bin\Hostx64\x64）也放在 PATH 里。
配完之后，新开一个 cmd 窗口执行 qmake -v，能输出 Qt 版本信息就说明路径生效。注意旧窗口不会刷新环境变量，测试时一定要新开终端。这个细节导致很多人以为没配成功，实际只是用了旧窗口。
4. Ubuntu 下搭建 Qt 开发环境的实操记录
4.1 用系统包管理器安装还是官方安装器
Linux 下装 Qt 有两条路。一条是 apt 直接装系统包：
sudo apt update sudo apt install qtbase5-dev qtcreator这条路的好处是快、依赖自动解决，但装出来的 Qt 版本通常比官方落后，且 Qt Creator 版本也可能不是最新的。另一条是下载官方 .run 离线安装器，在 Ubuntu 下执行：
chmod +x qt-opensource-linux-x64-5.15.2.run ./qt-opensource-linux-x64-5.15.2.run交互界面跟 Windows 一样，勾选组件时注意把 Desktop gcc 64 和 Qt Creator 选上。装出来的路径默认在 ~/Qt 或 /opt/Qt，看安装时指定的目录。
我给 Ubuntu 用户的实际建议是：如果你只是日常练手，apt 装一套完全够用；如果你要复现公司或网络课程的依赖版本，用官方 .run 安装器更可控。两条路我都走过，.run 装的 Qt 目录更干净，卸载也方便，缺点是占用磁盘空间比 apt 版本更大。
4.2 装完后的权限和启动问题
Ubuntu 下装完 Qt 最常见的问题集中在两点：第一个是 .run 安装完成后，Qt Creator 启动时缺少 xcb 平台插件，报错类似 "could not find the Qt platform plugin xcb"。这个报错几乎都是系统缺少 OpenGL 和 xcb 相关运行库，执行：
sudo apt install libxcb-xinerama0 libxkbcommon-x11-0 libgl1-mesa-dev就能解决绝大部分情况。
第二个是如果当前用户无权限写安装目录，Qt Creator 的配置写不进去，会出现"闪退"或"设置无法保存"。解决办法是确保安装目录的所有者是当前用户：
sudo chown -R 用户名:用户名 /opt/Qt4.3 用一个控制台程序验证环境
环境装没装好，最有效的验证是编译一个小程序。命令行方式最直接，写一个 main.cpp：
#include <QCoreApplication> #include <QDebug> int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); qDebug() << "Qt environment ok"; return 0; }然后：
qmake -project qmake make ./项目名能输出 "Qt environment ok"，说明 qmake、编译器、运行库全部正常。这一步比直接开 Qt Creator 建项目更能定位问题——如果命令行编译失败，问题出在工具链；命令行编译成功但 IDE 里跑不起来，问题大概率出在 Qt Creator 的 Kit 配置上。
5. 安装后的验证、常见报错与卸载要点
5.1 那个著名的 qpa 平台插件报错怎么一次性解决
"Cannot find the Qt platform plugin 'windows'" 绝对是 Qt 新手排名第一的拦路虎。这个报错的核心原因是程序运行时找不到 platforms 插件目录，也就是 Qt bin 目录下的 platforms 文件夹里的 qwindows.dll。
三种场景最容易触发：
- 直接双击运行编译出的 exe，没经过 Qt Creator，且 PATH 里没有 Qt bin
- 把 exe 拷到别的机器，只带了 exe 没带 Qt 的 DLL
- 用 windeployqt 部署时，部署目录结构不对
排查思路按三步走。先确认环境变量 PATH 里有没有 Qt 的 bin 路径，没有就加上。第二，检查 bin 目录下 platforms 文件夹是否存在，如果缺失，重装对应组件或者从完整安装里补拷。第三，不要依赖 exe 同目录放一个 platforms 文件夹，而是用官方推荐的 windeployqt 做部署。
发布程序时我固定用这个命令：
windeployqt 你的程序名.exe它会自动拷贝程序依赖的所有 Qt DLL、platforms 插件和样式插件。
5.2 安装期常见报错速查
| 报错现象 | 可能原因 | 解决办法 |
|---|---|---|
| 安装器解压失败或卡住 | 下载的安装包损坏 | 校验哈希，重新从镜像下载 |
| Kit 显示编译器警告 | 缺少 VS Build Tools 或编译器路径不对 | 补装对应版本 C++ 开发工作负载 |
| 编译报 msvcp140.dll 找不到 | 缺少 VC++ 运行库 | 安装 VC++ 2015-2022 运行库 |
| qmake 命令不存在 | 环境变量未配置 | 手动添加 Qt bin 到 PATH 并新开终端 |
| 安装完成但 Qt Creator 打不开 | 显卡驱动或 OpenGL 库缺失 | 更新显卡驱动或安装 mesa 相关依赖 |
5.3 卸载 Qt 时最容易被忽略的事
卸载 Qt 不是把整个目录删掉就完事。Windows 下要用 Qt 安装目录里的 MaintenanceTool.exe，选择"卸载"模式，它能清理注册表和快捷方式。直接删目录会留下一堆垃圾项，之后重装容易出奇怪问题。
特别提醒三点：第一，卸载前先检查有没有正在运行的程序占用 Qt 的 DLL；第二，卸载完记得清理环境变量里的 Qt 相关 PATH，否则换版本后旧路径会残留；第三，如果你装过多个 Qt 版本，建议只保留一个主用版本，其他全部删掉，版本间交互的 PATH 冲突是我见过最多的问题来源。
最后说点个人体会。Qt 安装这件事，百分之八十的问题出在版本和编译器混搭，剩下的百分之二十是路径和环境变量。很多人遇到 qpa 插件报错就重装系统，其实从 PATH 和 platforms 目录入手十分钟就能解决。装好环境之后，后续再看信号槽、多线程 moveToThread、自定义 QAbstractTableModel 这些机制都会顺畅很多。先别急着优化界面、折腾大框架，把环境稳定住，后面的路自然好走。
