做Qt开发的人几乎都经历过这样一个阶段想装个Qt打开官网却一脸懵版本多得像超市货架上的同款饮料在线安装器和离线包又不知道选哪个装完之后编译器套件配不上、模块找不到折腾一晚上还没跑起来第一个窗口。这两年因为工作原因我在Windows、Ubuntu、嵌入式ARM板子上反复装过好多遍Qt从5.9到6.8都碰过踩过的坑攒了不少。正好这次趁2025年4月28日重新整理这篇文章把“下载安装Qt各版本”这件事一次讲透。这篇内容会覆盖几个关键问题不同版本怎么选、在线安装器怎么用、离线安装包从哪里搞、装完怎么配置环境、Windows下版本冲突怎么解、Ubuntu 20.04下怎么搭Qt交叉编译环境最后还给了一份高频报错排查速查表。不管是准备入门Qt的初学者还是需要维护多版本环境的老人都能在里面找到能直接抄作业的部分。1. 下载前必须想明白的几件事很多人一上来就直奔“下载”结果卡在第一步到底该下哪个版本这里先说一句大实话Qt的下载安装本身不复杂真正麻烦的是安装之前的选择题。想清楚下面三个问题后面基本就是一路下一步。1.1 版本怎么选5.15.2、5.14.2还是6.x打开Qt官网或者镜像站你会看到一长串版本号。对新手来说最友好的两个判断维度是“是否长期支持版本”和“是否开源免费”。Qt 5.14.2最后一套还比较“复古”的安装包开源离线包友好度较高很多老项目、工业软件、教学课件还在用它。Qt 5.15.2必须单独说一下这是很多国内开发者心里的“白月光”。原因很简单5.15.2是开源协议下最后一个能比较方便拿到离线安装包的LTS版本。再往后的5.15.3、5.15.4虽然也存在但二进制安装包官方只对商业用户提供开源用户要么自己编译源码要么用其他方式获取。所以如果你要维护老项目、用稳定工具链、又不想在线安装5.15.2几乎是首选。Qt 6.5/6.8新的LTS版本6.5是Qt 6系列里公认比较稳定的长期支持版6.8则是当前主推的LTS新项目建议直接用6.5以上部分模块比如Qt Quick、多媒体框架6.x改动大从5.x升过来需要适配。还要注意架构选择x86/x64、arm64这些不说了Windows下还有MinGW和MSVC的区分Linux和macOS则是不同工具链。下载之前先问自己一句我这台机器上装了什么编译器没有编译器的话后面还得单独装。1.2 在线安装器还是离线安装包这个选择直接决定你要不要注册账号、要不要挂代理换镜像。在线安装器一个几MB的小程序运行后手动勾选需要组件边下边装。优点是灵活想装什么模块自己勾磁盘占用可控缺点是国内网络条件下下载速度不稳定而且必须要有Qt账号登录。离线安装包一个完整的“全家桶”安装包下载后本地直接安装不依赖网络适合内网环境、离线开发设备、或者在一堆机器上重复安装。缺点是体积巨大动辄几个GB而且官方对离线安装包的限制越来越严格不是每个版本都给你放出来。1.3 编译器套件怎么选MinGW还是MSVC这个问题新手必踩。Qt本身的库是有编译依赖的你用MinGW版的Qt库就必须用MinGW版的编译器用MSVC版就必须用Visual Studio那套工具链。混着来链接阶段直接教你做人。套件类型对应编译器适用场景调试器MinGWGNU GCCWindows移植版轻量开发、免装VS、安装包小GDBMSVCVisual Studio编译器cl.exeWindows深度集成、商业项目、驱动/COM开发CDB/WinDbg我个人的习惯是自己练习、做小工具、课程设计选MinGW版做商用项目、需要调Windows底层API或者要给别人交接Visual Studio工程选MSVC版。两种都可装不影响切换只要记得每个版配对应编译器就行。2. 官方在线安装器下载与安装实操确定好版本和编译器后正常的安装路线就是走官方在线安装器了。这个方法最大的优点就是省心官方维护模块全版本新。下面把完整流程过一遍。2.1 从官网下载在线安装器打开Qt官方下载入口找到下载按钮能看到两个大方向一个是给商业用户的Qt for Device Creation另一个是给开源用户使用的Open Source版本。我们通常选择后者进入后下载对应平台的online installerWindows就是.exe文件Linux是.run文件macOS是.dmg。这里要提醒一句不管从哪个入口进来的认准后缀带online字样的文件才是在线安装器。很多新手顺手把网页上的某个安装包当成全包下载结果发现是个几百MB的“引导程序”——其实那也算在线安装器之一只是它也要联网。下载速度如果很慢建议直接用国内镜像站的online installer副本比如清华、中科大镜像的qt/online_installers/目录里面每个时期的安装器都有归档选最新的即可。这个操作完全正规镜像内容和官方一致只是下载连接速度不同。2.2 安装过程中的账号登录Qt的在线安装器支持使用Qt账号登录。没有账号就现场注册一个邮箱验证一下就行。以前在线安装器允许跳过登录直接安装开源版本现在基本都强制要求登录这是官方许可协议的要求不用慌按照提示走即可。登录后安装器会列出一堆版本和组件这时候很多人就懵了不知道该勾什么。我第一次装的时候把所有列出来的全勾上结果磁盘直接少了40GB而且很多组件根本用不上。现在我的选择策略是这样需要哪个版本就展开那个版本的树形目录其他版本一律不勾。2.3 组件勾选策略与磁盘空间控制展开某个具体的Qt版本比如Qt 6.5.3 LTS后下面会按套件分为多个子项比如MinGW 14.2.0 64-bit、MSVC 2022 64-bit、Sources等。这里重点讲一下哪些必须勾你需要的编译器套件比如MinGW用户就勾选对应的MinGW开头的项目。注意如果列表里没有编译器项安装器可能把它放到单独的“Developer and Designer Tools”分类里需要展开确认。Qt Debug Symbols和Qt Sources正常情况下不必勾。Debug Symbols体积大且只在调试标准库内部时才有用Sources是源码普通开发用不到真要自定义编译再回去搞源码。Additional Libraries附加模块这里非常关键。Qt Charts、Qt Data Visualization、Qt SerialPort、Qt Multimedia、Qt WebEngine等都属于附加模块默认不勾需要按需求勾上。很多“unknown module(s) in Qt: serialport”的报错就是因为这里没勾。组件的安装逻辑是别贪多但要“宁全勿缺”。如果项目用到某个模块你没装后面补装要重新跑安装器麻烦得很。磁盘空间有限的话建议只保留一个编译器套件和常用附加库其他忽略。3. 离线安装包获取思路与镜像加速有些人可能需要离线安装包比如单位内网机器、要批量部署多台机器、或者在线安装器老是下载到一半断掉。这时就需要换一条路直接获取完整的离线安装包。这里分享两个实用手段archive路径与aqtinstall工具。3.1 为什么官方离线包这么难找因为绝大多数新版本的离线安装包不再放在下载首页而是归档在download.qt.io/archive/之下。进入archive后会看到两个常用目录qt/5.15/5.15.2/这里能直接拿到qt-opensource-windows-x86-5.15.2.exe这样的完整离线安装包文件名中带完整版本号选对应平台直接下载。qt/6.5/6.5.3/以及qt/6.8/路径部分新版本只有源码包和在线组件元数据不一定有全量离线exe。Qt 6.5.0的离线安装原始包里还有个例外是官方发布了离线包但到了后续补丁版本就没那么全了。另外Windows下Qt新版的离线安装包经常区分MinGW和MSVC下载前一定看清命名。比如qt-opensource-windows-x86-5.15.2.exe32位/64位集成了MinGW的版本qt-opensource-windows-x86-5.15.2-msvc2019_64.exe面向MSVC 2019的版本如果在官网下载慢直接使用镜像。国内的清华TUNA镜像和中科大USTC镜像都会同步Qt官方archive目录浏览器进入镜像站的qt/archive/后与官方路径一一对应用IDM或浏览器自带下载器都能跑满带宽。3.2 aqtinstall命令行精确下载指定版本与模块如果你不想用浏览器翻目录推荐一套绝佳工具aqtinstall。它本质上是一个Python包用命令行脚本直接访问Qt官方源把指定版本、指定套件、指定模块的安装包拉到本地并自动解压。很多CI流水线环境比如GitHub Actions就是这么干的。安装方法pip install aqtinstall下载特定版本示例# 下载 Qt 5.15.2 的 Windows MSVC 2022 64位如需minGW把后面的套件名换掉 aqt install-qt windows desktop 5.15.2 win64_msvc2019_64 # 同时安装附加模块 serialport、charts aqt install-qt windows desktop 5.15.2 win64_msvc2019_64 -m qtserialport qtcharts如果网络不太好还可以给aqt挂国内的opensource镜像参数aqt install-qt --base https://mirrors.tuna.tsinghua.edu.cn/qt windows desktop 5.15.2 win64_mingw81这个命令会把Qt库文件直接解压到当前目录下比如C:\Qt\5.15.2\msvc2019_64。注意这时只拿到了Qt库本体没有Qt Creator也没有编译器。所以用aqt下载后通常还需要单独安装Qt Creator和MinGW或者直接用VS编译配合命令行工具。使用aqt的几个注意事项下载前先确认目标版本和套件名存在可以用aqt list-qt windows desktop --spec 5.15.2查看支持的套件架构版本名一定要写完整6.5.3不能省略补丁号另外aqt默认使用官方源如果感觉速度不对劲就换上面说的镜像参数。3.3 镜像站离线包安装的后续操作镜像站下载下来的离线安装包本质和官网一样运行后按提示安装即可。这里也要注意离线安装包虽然体积大但它不会强制你登录账号所以内网环境部署时推荐优先用离线包。离线包安装完之后最好检查一下环境变量和Qt Creator里的Qt Versions路径是否自动识别。一般情况下离线安装器会自动写入注册表或配置Qt Creator路径但如果你把Qt装到非默认目录后续务必手动去“工具→选项→Kits→Qt Versions”里添加路径。4. Windows环境下的配置与版本冲突处理安装只是第一步配置环境才是让Qt真正能用的关键。尤其是当机器上同时存在多个Qt版本、多个编译器时版本冲突能让人抓狂。这一节把我踩过的坑和解决办法集中说一遍。4.1 环境变量、Path与Qt Creator的Kit配置Qt程序运行时需要找到对应的DLL如果Path里同时存在多个Qt版本的bin目录系统会按顺序搜索。所以配置环境的本质就是让“当前要用的那一套”排在最前面。以Windows Qt 5.15.2 MinGW为例安装完成后需要保证以下几类路径被正确设置QTDIR指向C:\Qt\5.15.2\mingw81_64PATH把%QTDIR%\bin放在靠前位置PATH把MinGW的bin目录比如C:\Qt\Tools\mingw810_64\bin也放进去PATH如果需要调试把C:\Qt\Tools\mingw810_64\bin里的gdb所在目录加进去Qt Creator里的Kit配置则要对应关系正确Qt Version选5.15.2编译器选MinGW 8.1.0CMake选对应的版本调试器选GDB。如果这些配置串了比如用MSVC编译器去编译MinGW版本的Qt库链接阶段会崩得体无完肤。判断配置是否正常的技巧打开Qt Creator的“工具→选项→Kits”看Kit前面的图标有没有黄色感叹号有感叹号说明配置缺失或版本不匹配。点开详情逐项检查编译器路径、qmake路径、CMake路径是否都存在尤其是qmake的路径经常有人装了两个版本结果qmake指向了错误的Qt目录。4.2 彻底解决“cannot mix incompatible Qt library”这类版本冲突这个报错非常典型报错信息类似“cannot mix incompatible Qt library (5.15.3) with this library (5.15.2)”。原因其实不复杂你的程序编译时链接的Qt库和你运行时加载的Qt库版本不一致。举一个真实场景某天我用Qt 5.15.2编译了一个程序运行时程序爆出“cannot mix incompatible Qt library”排查后发现是因为我在系统的PATH里先写入了另一个版本的Qt 5.15.3的bin目录。程序在启动时会加载Qt5Core.dll而系统根据PATH顺序把5.15.3的Qt5Core.dll加载进来了和自己编译时用的5.15.2版本不一致自然就炸了。解决思路清理PATH中的多余Qt bin目录只保留当前项目使用的版本。清理build目录重新qmake并构建确保所有中间文件都是基于同一个Qt版本生成的。检查IDE或者命令行里的环境变量尤其是QMAKE、QTDIR是否是全局覆盖的。如果确认环境变量没问题但运行还是报错用Dependencies.exe或者Process Explorer查看程序实际加载的Qt5Core.dll路径直接定位到错在哪。经验补充排查环境变量问题时不要只盯着系统变量还要盯着用户变量以及Qt Creator的“构建环境”设置。Qt Creator里可以在“项目→构建环境”处看到实际生效的环境变量很多时候系统Path没问题但那里覆盖成了另一个版本。4.3 卸载Qt的正确方式“卸载Qt”听起来简单很多人直接删安装目录结果后来装新版时候各种残留冲突。正确的流程是如果安装的是在线安装器版本进入安装目录找到MaintenanceTool.exe运行选择“移除所有组件”跟随向导卸载。如果离线安装包会安装一个Uninstall的卸载器同理用它卸载。手动删除安装目录残留文件并清理环境变量中与该版本Qt相关的条目。检查C:\Users\用户名\AppData\Local\Qt和AppData\Roaming\QtProject等配置目录如果不再需要一并删除。不推荐直接删除Qt目录是因为旧的注册表项、配置文件会影响后续安装。多花两分钟用卸载工具后面省两小时。5. Ubuntu 20.04下搭建Qt交叉编译环境热搜词里有“ubuntu-20.04 安装 qt 交叉编译环境”这个需求在嵌入式开发、工控行业非常普遍。我简单梳理一下思路在x86的Ubuntu 20.04开发机上编译出ARM架构目标板能跑的Qt程序需要两套环境一是本机的Qt开发环境二是交叉编译工具链和目标架构的Qt库。5.1 安装本机Qt开发依赖如果是通过在线安装器或apt安装Qt推荐两条路用apt安装Qt5基础开发包sudo apt update sudo apt install build-essential libgl1-mesa-dev libfontconfig1-dev libdbus-1-dev libfreetype6-dev libxkbcommon-x11-dev libxcb* dev libx11-dev libx11-xcb-dev libxext-dev libxfixes-dev libxi-dev libxrender-dev libxcb1-dev libxcb-glx0-dev libxcb-keysyms1-dev libxcb-image0-dev libxcb-shm0-dev libxcb-icccm4-dev libxcb-sync-dev libxcb-xfixes0-dev libxcb-shape0-dev libxcb-randr0-dev libxcb-render-util0-dev libxcb-xinerama0-dev libxcb-xkb-dev libxcb-util0-dev libasound2-dev libpulse-dev手动下载Qt源码交叉编译对于嵌入式目标板推荐用官方源码包自行configure。由于HelloWorld用apt装的Qt是x86版本不能直接给ARM用所以想交叉编译就不能只靠它。理解这点很重要交叉编译环境的核心资源是目标架构的Qt库。5.2 准备交叉编译工具链以常见的ARM Cortex-A53平台为例我一般用Linaro提供的aarch64-linux-gnu工具链也可用开发板厂商提供的交叉工具链。安装方式sudo apt install gcc-aarch64-linux-gnu g-aarch64-linux-gnu装好后验证aarch64-linux-gnu-gcc --version如果开发板是32位ARM比如Cortex-A7就装sudo apt install gcc-arm-linux-gnueabihf g-arm-linux-gnueabihf交叉编译工具链决定了后续编译出的二进制格式千万别装错架构。用file命令查看现有可执行文件的架构也能验证自己是否选对了工具链。5.3 编译目标平台的Qt库并配置qmake拿到Qt源码后在源码目录下运行configure脚本指定交叉平台参数。以aarch64为例./configure -prefix /opt/qt5.15.2-arm -xplatform linux-aarch64-gnu-g \ -release -opensource -confirm-license \ -nomake examples -nomake tests \ -no-opengl -no-dbus这里说明几个参数-prefix最终安装路径建议放在独立目录不与本机Qt混在一起。-xplatform linux-aarch64-gnu-g使用的是Qt源码里自带的交叉平台配置。如果没有现成的配置文件需要自己仿照mkspecs/linux-arm-gnueabi-g创建一个新的目录修改qmake.conf指向交叉编译器。-no-opengl -no-dbus按目标板硬件裁剪功能板上没有GPU就不要开OpenGL没有DBus就关掉DBus否则后续链接会报一堆“找不到库”的错误。configure完成后执行make -j$(nproc) make install把Qt库安装到/opt/qt5.15.2-arm下。这时候得到的qmake就是交叉qmake/opt/qt5.15.2-arm/bin/qmake -v5.4 用交叉qmake组织项目并部署到目标板在开发机的Qt Creator里新建项目时可以在“工具→选项→Kits”里添加一个“Device”类型的远程ARM套件或者直接使用命令行构建/opt/qt5.15.2-arm/bin/qmake your_project.pro make编译出来的可执行文件是ARM架构的通过arm-linux-gnueabihf-strip或者aarch64-linux-gnu-strip瘦身后再连同Qt运行库一起scp到开发板。运行前把开发板的环境变量指到部署的Qt库路径export LD_LIBRARY_PATH/opt/qt5.15.2-arm/lib:$LD_LIBRARY_PATH一个容易踩的坑交叉编译时经常出现找不到libts、libjpeg、libpng等依赖库的情况。这些第三方库也必须交叉编译一份放到-prefix指定的目录里然后在configure时用-I和-L参数指定头文件和库文件路径。没有这些依赖库Qt的某些插件和模块会直接默认禁用编译出的程序到板子上运行起来一堆功能缺失。如果纯粹用Qt Widgets模块做简单界面不涉及多媒体、网络、数据库等依赖通常比较少。但一旦用了Qt WebEngine、Qt Multimedia这类重量级模块交叉编译的复杂度会显著上升。建议做嵌入式UI评估前先确认目标板是否真的需要这些重量模块能用轻量方案就用轻量方案反而能少踩很多坑。6. 高频问题排查速查表最后把这些年在安装配置Qt过程中遇到的高频问题整理成速查表方便大家直接按图索骥。6.1 模块缺失与加载类问题报错现象常见原因解决方案:-1: error: unknown module(s) in Qt: serialport安装时未勾选Qt SerialPort模块重新运行安装器或aqt补装Qt SerialPort模块编译报错找不到QtCharts/QChartView未安装Qt Charts附加模块勾选Qt Charts模块并重新构建项目双击exe提示“找不到Qt5Core.dll”PATH路径中缺少Qt bin目录或该目录未包含DLL将对应Qt版本的bin目录加入系统PATH或程序目录下拷贝所需DLL启动闪退日志提示“could not find platform plugin”Qt程序缺少platforms插件目录用windeployqt部署后确认platforms/qwindows.dll存在cannot mix incompatible Qt library (5.15.3) with this library (5.15.2)运行时加载了不同版本Qt DLL清理PATH、build目录确认程序加载的是项目编译时的Qt版本windeployqt打包这个细节值得多说一句打包发布时在Qt命令行里执行windeployqt 你的程序.exe它会自动把依赖的DLL和插件目录拷到exe旁边但对某些附加模块如Qt Charts、Qt WebEngine可能不全生成完毕后建议再用Dependencies.exe扫描一遍缺什么补什么。6.2 安装、工具链与开发环境问题问题说明建议在线安装器下载速度慢网络问题使用清华/中科大镜像下载安装器或离线包Qt Creator提示找不到编译器未安装MinGW或VS组件在Kits中手动选择编译器路径或重装对应编译器VSCode里配置Qt Designer需要安装Qt Tools扩展并设置Qt路径在设置中把qtdesigner路径指向%QTDIR%\bin\designer.exe卸载Qt后残留文件直接删目录导致注册表/环境变量残留使用MaintenanceTool.exe卸载清理AppData与PathQt 5.15.2与6.x共存多版本环境冲突分离环境变量Qt Creator中为每个版本建独立Kit切换时确认PATH顺序程序在别人的机器上运行崩溃缺少运行库装了错误的Qt运行库发布时使用对应版本windeployqt优先Release构建并带上VC运行库或MinGW运行库另外想装Qt Designer独立工具的话官方提供的Qt Creator里本身就集成了不需要单独下载。VSCode用户通过插件调用时直接指向Qt安装目录下的bin/designer.exe就能打开UI编辑器。千万注意不要混用不同编译器版本编译出来的designer.exe窗口控件显示会异常。还有一类问题经常看到嵌入式开发时Linux跑Qt还是LVGL。这个其实属于方案选型问题如果设备资源紧张、界面简单、追求启动速度和低功耗LVGL很合适如果业务复杂、需要丰富控件和高级布局、又希望复用桌面Qt技能选Qt更合适。交叉编译安装Qt的前期成本虽高但后续的开发和维护效率通常更好。7. 一些实在的安装体验与建议Qt的安装其实没有想象中那么可怕它只是一个“版本选型模块选择工具链匹配”的组合题。我见过太多人卡在unknown module(s) in Qt: serialport这类小问题上归根到底还是安装时少勾了几个模块。几点经验总结给大家新项目优先Qt 6.5以上如果带不动比如要兼容老代码再回退到5.15.2。离线部署、内网开发、课程实验推荐5.15.2离线包但要注意官方没有为5.15.3提供免费离线包想追求新补丁就用6.5.3或6.8的离线包。附加模块宁可多装几个也不要漏serialport、charts、datavisualization、multimedia、svg都是高频选项装完省事。版本混用的修复永远先从PATH和build目录查起这一条能解决至少三成报错。交叉编译环境不是一次配好就一劳永逸的不同目标板、不同第三方库、不同Qt版本可能需要微调configure参数最好做好记录方便后续复用。按这套流程多走两遍你也会发现Qt的版本管理其实很清晰。如果实战中还有新的报错别慌先把报错信息完整贴到搜索引擎里大概率能找到同路人。自己动手装一次Qt比看十篇教程都有用。