我做了五年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. LinuxUbuntu 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的QPAQt Platform Abstraction抽象层使用。简单说Windows下没有这个变量时Qt会自动找平台插件但你把程序拷贝到其他机器时经常找不到就会报could not find or load the Qt platform plugin windows。常规做法是在程序启动前在代码或者批处理脚本中设置set QT_QPA_PLATFORM_PLUGIN_PATHD:\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%\QtProjectLinux下是~/.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被废弃改用了QRegularExpressionQT script模块在Qt 6里没了对应的脚本引擎需要自行集成老的QtWebEngine库命名和5.15不同编译参数调整比较大。只要你在切换时留意这些升级版本就不是噩梦。7. 最后聊点我自己踩过后的习惯装Qt这件事说到底是环境管理问题。我现在的固定流程是新机器先装编译器再装Qt离线包装完用Hello World验证一遍最后把所有配置截图存档。因为Qt的安装错误大多是在配Kit和配环境变量时出的每一步留个记录出问题时对照排查快得多。还有一个容易被忽略的点Qt官方在线安装器有个存储下载目录到本地缓存的功能首次安装时可以把所有下载的组件缓存到本地。这样下次重装系统直接用缓存包可以减少大量等待时间对于实验室里长期用同一套环境的人来说非常香。另外如果你经常做Qt嵌入式开发建议把自己的交叉编译环境写成脚本不要手动重复配置。因为交叉编译涉及的sysroot、qmake参数、目标板架构这些细节人脑记不住脚本能保证两次配置结果一致。我就吃过这个亏手动配置的交叉编译环境隔一个月后发现某个库忘了复制板子跑起来各种段错误浪费了两天时间。下载与安装看似只是人人都会的走路环节但恰恰是这第一步决定了后续开发的顺不顺畅。把这篇文章里的细节落实了你后面写代码的日子会轻松一大截。