我做了五年Qt开发，见过太多新人卡在第一步——不是代码不会写，而是这个工具根本装不上，或者装上之后各种奇奇怪怪的报错。印象最深的一次，一个同事在家里的电脑上装了个Qt 5.15.3，结果拿到公司用5.15.2的工程直接编译不过，报了个cannot mix incompatible qt library (5.15.3) with this library (5.15.2)，折腾了一天才发现是安装时没注意版本细节。今天就把Qt下载与安装这些事彻底讲透，从版本怎么选、安装包怎么下、环境怎么配，到那些安装后立刻会遇到的坑，全部捋一遍。不管是Windows还是Ubuntu，不管是只做桌面端还是需要交叉编译，这篇文章都够用了。
1. Qt安装前必须搞清楚的三件事：版本、套件、许可证
很多新手上来就搜"qt下载"，然后随便点一个链接就装了，这是大忌。Qt不是一个单一软件，而是一整套跨平台C++图形界面框架，安装之前你得先明白自己在装什么。
1.1 Qt的版本号到底该怎么读
Qt的版本号遵循A.B.C格式，比如5.15.2、6.5.3。A和B是主版本号，C是补丁版本号。补丁版本一般只修bug，不新增功能，所以同一个主版本内的补丁版本理论上可以互相替换。但注意，Qt官方对二进制兼容性有严格的保证：如果你想用5.15.1的库去链接5.15.2编译出来的代码，大概率会报我刚才说的那个incompatible library错误。所以安装时一定要记清楚自己项目依赖的精确版本号。
从Qt 6开始，版本号后面的后缀逻辑也变了。6.x系列里，每个小版本比如6.2、6.5都是LTS（长期支持版本），官方会提供长期维护。如果你做的是商用项目，优先选LTS版本；做学习或短期原型，用最新版也行。我个人建议：新项目直接用Qt 6.5以上的LTS，老项目如果依赖5.x的模块，那就老老实实用5.15.2——很多第三方库至今只兼容到5.15。
1.2 编译器套件（Kit）的选择：MinGW还是MSVC
这是Windows平台最容易懵的地方。Qt本身是框架，但编译时需要一个C++编译器。Qt官方提供两套预编译库：
- MinGW套件：使用MinGW-w64编译器。这个编译器是GCC在Windows上的移植版，自带一个MinGW版的Qt Creator，装上就能用，不需要额外装Visual Studio。适合新手、跨平台开发，但调试器和性能略逊于MSVC。
- MSVC套件：使用微软的Visual C++编译器，需要预先安装Visual Studio或单独的Build Tools。性能好，调试体验上乘，Windows API兼容性最好。但注意MSVC版本的Qt库只能用对应大版本的MSVC编译器，比如msvc2019_64的库只能用VS2019的编译器。
选择逻辑很简单：如果你只在本机跑，用MinGW省事；如果要发布给Windows用户，并且用到一些Windows底层API，建议MSVC。另外，如果要用Qt的WebEngine模块，MSVC是必须的，MinGW下这个模块没有预编译包。
1.3 开源版和商业版，以及许可证坑
个人开发者、学习用途、甚至很多企业内部自用项目都可以用开源版（LGPL/GPL许可证）。开源版的安装包里会有一个登录Qt账号的选项，你可以注册一个免费账号，然后用开源版安装器。注意：开源版不允许使用某些商用模块，但绝大多数桌面开发用不到。
商业版需要付费订阅，提供额外的专有模块和官方技术支持。这里有个容易踩的坑：你在Qt官网页面上点"Download"，默认可能引导你到商业版试用的页面。找"Open Source"链接，或者直接用官方开源版安装器的直链。我见过有人装了商业试用版，到期后一堆模块被锁，工程直接废了。
2. 官方安装包与离线安装包：下载源的选择策略
下载Qt看似简单，实际上很多人卡在下载速度慢、安装包找不到正确版本这些事上。下面说说我实测过的几种下载路径。
2.1 在线安装器（Qt Online Installer）的正确打开方式
Qt官方推荐的方式是下载一个几百KB的在线安装器，它会在安装过程中拉取你勾选的组件。但在线安装器有两个问题：一是需要登录Qt账号，二是默认从官方服务器下载，在国内经常慢到怀疑人生，甚至中途断线。
我的建议是：在线安装器只用来做组件管理，首次安装尽量用离线包。安装器启动后，你可以选择特定版本的Qt组件，但如果你网络条件一般，还是先考虑下面说的离线包。
另外，在线安装器安装完毕后会生成一个MaintenanceTool，这个工具以后可以用来增删组件、更新Qt版本、卸载Qt。保留好它，别删。
2.2 离线安装包在哪里找：镜像站与分版本下载
Qt官方其实提供了离线安装包，但在官网入口藏得深。方法是访问Qt的官方镜像站点列表，或者直接找download.qt.io下的archive/qt/目录。比如你想下载5.15.2，路径是archive/qt/5.15/5.15.2/，里面会有对应Windows、Linux、macOS的离线安装包，命名类似qt-opensource-windows-x86-5.15.2.exe。
国内用户强烈建议用清华或中科大的镜像源，速度提升明显。比如清华源：mirrors.tuna.tsinghua.edu.cn/qt/，镜像里同样有archive目录，路径结构和官网一致。我用清华源下载5.15.2的离线包，2.5GB大概10分钟就拉完了，官方源可能要一小时。
2.3 安装时组件的选择：精简还是全装
离线安装包虽然大，但安装时你可以勾选组件。这里有个经验：第一遍不要贪多。只需要勾选你当前平台的Qt库（比如Qt 5.15.2 > MinGW 8.1.0 64-bit），再加一个Qt Creator（如果安装包里没带的话）。其他模块比如Android、Sources、Qt Debug Information Files，用的时候再通过MaintenanceTool补，哪怕需要重新打开在线安装器也比一开始装一堆占硬盘强。
特别注意：如果你需要调试Qt源码，一定勾选Sources组件。没有源码，你进了断点发现只能看到汇编，那可太痛苦了。
3. Windows平台安装实操：从下载到第一个Hello World
下面这一段是我在Windows 10/11上反复验证过的完整流程，按照步骤来，基本一次成功。
3.1 环境准备：装好编译器再动Qt
如果你打算用MSVC套件，先装Visual Studio 2019或2022。不用装完整版，在Visual Studio Installer里勾选"使用C++的桌面开发"工作负载就行。这一步很多人会漏掉，导致后面Qt Creator里看不到MSVC套件，白白浪费时间。
如果打算用MinGW，就不需要单独装编译器，因为Qt离线包里的MinGW套件已经自带了GCC工具链。不过要确认你下载的Qt安装包对应的MinGW版本，比如5.15.2对应的MinGW 8.1.0，别拿错。
3.2 安装步骤详解
以Qt 5.15.2 Windows离线包为例：
- 解压或直接运行安装包（不建议解压到有中文或空格的路径，比如
D:\Qt\5.15.2是好路径，C:\Program Files\Qt虽然能装但后面一些脚本容易出问题）。 - 安装程序会要求登录Qt账号，没有就现场注册一个，选个人用途即可。
- 选择安装目录，我习惯用
D:\Qt，因为后面手动配置环境变量方便。 - 组件选择页面，展开
Qt 5.15.2，勾选你需要的编译器库，比如MinGW 8.1.0 64-bit或MSVC 2019 64-bit。还要回到顶层勾选Developer and Designer Tools里的Qt Creator。 - 确认后开始安装，等待完成。安装结束，桌面会出现Qt Creator图标。
3.3 在Qt Creator里配置套件并运行第一个程序
打开Qt Creator后，如果你安装时带了编译器，会自动检测到套件。如果没有，手动添加：菜单"工具"->"选项"->"Kits"，在"编译器"标签页添加MinGW的g++，在"Qt Versions"里添加你安装的qmake.exe路径，最后Kits页里新建一个Kit，选好编译器和Qt版本。
测试一下：新建一个Qt Widgets Application，构建并运行，弹出一个空窗口，说明环境没问题。如果报错找不到编译器，大概率是套件配置不对，回上一步检查。
3.4 环境变量：PATH里要不要加Qt
很多教程让你把D:\Qt\5.15.2\mingw81_64\bin加入系统PATH。我的建议是：别加。因为Qt Creator本身会管理好运行时库的搜索路径，加了反而可能和你系统里其他Qt版本冲突，那个cannot mix incompatible qt library的经典报错，一半都是PATH里混入了不同版本Qt的bin目录导致的。
你只需要在命令行里临时用qmake时，手动把Qt的bin目录加进当前会话的PATH即可。
4. Linux（Ubuntu 20.04）下安装Qt与交叉编译环境配置
Linux下装Qt有两个流派：用系统包管理器装（apt install qt5-default之类），或者用Qt官方离线安装包。系统包管理器方便，但版本老、bug修得慢；官方离线包版本新、可控，但依赖库要自己解决。我建议开发者用官方离线包，在嵌入式开发场景下尤其如此。
4.1 Ubuntu 20.04安装Qt 5.15.2的个人实践
先装基础依赖库，否则后续编译你可能遇到各种找不到头文件的错误：
sudo apt update sudo apt install build-essential libgl1-mesa-dev libglu1-mesa-dev libxkbcommon-x11-dev libxcb-xinerama0-dev然后下载Linux版的Qt 5.15.2离线安装包，比如qt-opensource-linux-x64-5.15.2.run。给它执行权限：
chmod +x qt-opensource-linux-x64-5.15.2.run ./qt-opensource-linux-x64-5.15.2.run安装过程跟Windows差不多，选择组件时勾选Desktop gcc 64-bit。安装目录建议放在家目录下，比如~/Qt/5.15.2/gcc_64，这样权限问题少。
安装完运行Qt Creator时，可能报错libxcb-xinerama0缺失，如果之前没装基础依赖就会遇到。用ldd命令查看可执行文件依赖，缺哪个装哪个。
4.2 配置交叉编译环境：从工具链到qmake的改造
如果你的目标板是ARM架构（比如基于ARM的工控设备），需要在Ubuntu上配置交叉编译Qt环境。交叉编译的精髓是：用x86的机器编译出能在ARM设备上运行的Qt程序，所以编译器要换成arm-linux-gnueabihf-g++之类的交叉编译器。
完整步骤我先说场景：你在Ubuntu 20.04上想用Qt写程序，然后交叉编译到一款ARM Cortex-A53的开发板上。那么你需要：
- 下载并解压交叉编译工具链，比如
gcc-linaro-7.5.0-2019.12-x86_64_arm-linux-gnueabihf。 - 用这个工具链重新编译一套Qt交叉编译库，或者直接下载对应目标板的Qt交叉编译库。这个过程比较复杂，网上教程容易踩坑的地方在于：sysroot路径要写对，
qtbase配置时要用-xplatform参数指定目标平台，比如-xplatform linux-arm-gnueabi-g++。 - 配置好交叉编译工具链后，在Qt Creator里新建一个Kit，选择交叉编译器、交叉编译的qmake，设置好系统根目录（sysroot），这样就能在开发机上直接编译ARM程序了。
这里有个非常容易出错的地方：交叉编译时需要目标板的rootfs作为sysroot，否则链接器找不到目标板的系统库。很多人只配置了交叉编译器，没配sysroot，结果编译能过，链接时一大堆cannot find -lgl之类的错误。
4.3 交叉编译套件的验证小技巧
配置完成后，用交叉编译出一个最简单的Qt程序部署到板子上跑，这才能算环境OK。常见验证命令：
file hi_qt # 输出类似：hi_qt: ELF 32-bit LSB executable, ARM, ...如果file命令显示信息正确，说明交叉编译成功。部署到板子后，记得把交叉编译的Qt库也复制过去，并且设置环境变量QT_QPA_PLATFORM_PLUGIN_PATH指向板子上插件目录的位置，否则程序在板上跑起来黑屏、没界面，就是这个变量没设对。
5. 安装后立刻要处理的坑：库冲突、路径与环境变量
装完Qt只是开始，接下来这一部分几乎人人都会碰到，我挑几个代表性案例讲。
5.1 那个著名的cannot mix incompatible qt library错误
cannot mix incompatible qt library (5.15.3) with this library (5.15.2)，这个报错我见过不下二十次。根本原因是：你编译时用的是5.15.2的头文件，但运行时加载的就是5.15.3的Qt动态库，或者反过来。Qt会在初始化时检测版本，不匹配直接崩。
排查顺序：
- 查看你Qt Creator里选择的编译套件qmake路径，确认是哪个版本。
- 在系统的PATH环境变量里搜索是否有其他版本的Qt bin目录，有就清掉。
- 查看你项目的
.pro文件里是否硬编码了某个Qt路径，比如LIBS += -L/path/to/qt/5.15.3，这类手动指定路径经常引入版本错乱。
解决方案就是统一版本：要么把项目所有依赖都指向同一个Qt安装目录，要么把不需要的Qt版本卸载干净。
5.2 QT_QPA_PLATFORM_PLUGIN_PATH是什么，为什么必须配置
这个环境变量控制Qt的平台插件路径，主要由Qt的QPA（Qt Platform Abstraction）抽象层使用。简单说，Windows下没有这个变量时Qt会自动找平台插件，但你把程序拷贝到其他机器时经常找不到，就会报could not find or load the Qt platform plugin "windows"。
常规做法是在程序启动前，在代码或者批处理脚本中设置：
set QT_QPA_PLATFORM_PLUGIN_PATH=D:\Qt\5.15.2\msvc2019_64\plugins\platforms但更推荐的做法是：把需要的插件直接打包到你的程序目录下，然后把这个变量指向程序内部的plugins目录，而不是指向Qt安装目录。这样发行时更可控。
5.3 Qt Creator的临时文件与缓存引发的编译乱象
Qt Creator默认在C:\Users\用户名\AppData\Local\QtProject\qanalyzer之类目录存缓存。当你切换Qt版本后，旧缓存可能影响变量配置，导致编译用的还是老版本的库。我遇到过一种情况：换新版本Qt后，qmake还是指向老路径，编译时一直找不到新版库。
解决办法是：在Qt Creator菜单"工具"->"选项"->"构建和运行"->"套件"里，手动重新指定Qt版本路径；如果还不行，删除QtProject缓存目录（注意备份你自己的项目配置，项目文件里一般没有这个依赖）。删除缓存后重新打开Qt Creator，让它再检测一次。
5.4 我的发行版打包经验分享
这里有个发行打包的通用建议，也是很多新手容易忽略的：Qt程序发行时要带上对应编译套件版本的platforms、styles、imageformats等插件目录，以及必要的DLL。在Windows下最简单的办法是使用官方提供的windeployqt.exe，在命令行里迁行：
windeployqt --release your_app.exe它会把依赖的Qt文件自动复制到exe所在目录。但注意：windeployqt只解决Qt自带的依赖，如果你用了第三方库，还要自己手动复制。另外，如果程序在别人机器上双击没反应，多半是缺VC运行时库，GitHub上一堆开源VS版Qt程序就是死在没装VC++ Redistributable，所以给用户发行时最好附带一下。
6. 卸载与版本切换：想换Qt版本怎么办
Qt不是你用完就删那么容易的软件，卸载不干净，装新版本后会各种报错。
6.1 用MaintenanceTool彻底卸载
每个Qt安装目录下都有一个MaintenanceTool可执行文件。运行它，登录你的Qt账号，选择"卸载所有组件"，它会清掉整个Qt目录。这个方法最干净，建议优先用。
如果没有MaintenanceTool（比如你只某天手动复制了一个Qt包目录），那就纯手动删：删掉整个Qt安装目录，在Windows下还要清理%APPDATA%\QtProject和%LOCALAPPDATA%\QtProject，Linux下是~/.config/QtProject和~/.local/share/QtProject。环境变量里如果有Qt相关项，一并去掉。
卸载完重启Qt Creator，重新添加你新装的版本，这条链路我反复验证过。
6.2 多版本共存的管理方法
我自己的开发本上同时装了5.15.2和6.5.2，两个版本相安无事。秘诀就是：不同主版本的Qt安装到不同目录。比如一个在D:\Qt\5.15.2，另一个在D:\Qt\6.5.2。然后在Qt Creator的Kit配置里，分别给两个版本新建不同的Qt Version，不同的编译器套件。切项目时只要在左侧的"项目"模式里切换Kit即可。
但千万别让两个版本的bin目录同时出现在PATH里，这是引发库冲突的头号原因。调试时如果出现莫名其妙的崩溃，第一时间检查下当前用的Kit，是不是选错了版本。
6.3 一条卸载后最重要的验证步骤
卸载完旧版本，Windows下最好执行一次where qmake命令行，确认不再输出旧路径。Linux下用which qmake。如果还能找到，说明系统里还有残留的Qt环境变量或软链接，赶紧清理。否则新装的Qt可能被旧配置文件干扰，编译时固件找不到。
我有个习惯：在干净的系统上重装Qt之前，先做一次完整的备份。把项目目录备份好，然后放心折腾Qt本身。反正项目工程文件（.pro）跨版本迁移的成本通常比想象低，绝大多数写法在5.15和6.x之间改动不大。真要说有哪些不兼容，我把踩过的坑列在下面：
- Qt 6里
QRegExp被废弃，改用了QRegularExpression； QT += script模块在Qt 6里没了，对应的脚本引擎需要自行集成；- 老的
QtWebEngine库命名和5.15不同，编译参数调整比较大。
只要你在切换时留意这些，升级版本就不是噩梦。
7. 最后聊点我自己踩过后的习惯
装Qt这件事，说到底是环境管理问题。我现在的固定流程是：新机器先装编译器，再装Qt离线包，装完用Hello World验证一遍，最后把所有配置截图存档。因为Qt的安装错误大多是在配Kit和配环境变量时出的，每一步留个记录，出问题时对照排查快得多。
还有一个容易被忽略的点：Qt官方在线安装器有个"存储下载目录到本地缓存"的功能，首次安装时可以把所有下载的组件缓存到本地。这样下次重装系统，直接用缓存包可以减少大量等待时间，对于实验室里长期用同一套环境的人来说非常香。
另外，如果你经常做Qt嵌入式开发，建议把自己的交叉编译环境写成脚本，不要手动重复配置。因为交叉编译涉及的sysroot、qmake参数、目标板架构这些细节，人脑记不住，脚本能保证两次配置结果一致。我就吃过这个亏：手动配置的交叉编译环境，隔一个月后发现某个库忘了复制，板子跑起来各种段错误，浪费了两天时间。
下载与安装看似只是人人都会的"走路"环节，但恰恰是这第一步决定了后续开发的顺不顺畅。把这篇文章里的细节落实了，你后面写代码的日子会轻松一大截。
