企业官网建设流程全解析

做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那套工具链。混着来，链接阶段直接教你做人。

我个人的习惯是：自己练习、做小工具、课程设计，选MinGW版；做商用项目、需要调Windows底层API，或者要给别人交接Visual Studio工程，选MSVC版。两种都可装，不影响切换，只要记得每个版配对应编译器就行。

2. 官方在线安装器下载与安装实操

确定好版本和编译器后，正常的安装路线就是走官方在线安装器了。这个方法最大的优点就是省心，官方维护，模块全，版本新。下面把完整流程过一遍。

2.1 从官网下载在线安装器

打开Qt官方下载入口，找到下载按钮，能看到两个大方向：一个是给商业用户的Qt for Device Creation，另一个是给开源用户使用的Open Source版本。我们通常选择后者，进入后下载对应平台的online installer，Windows就是.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.exe（32位/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_64
• PATH：把%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.0，CMake选对应的版本，调试器选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版本不一致，自然就炸了。

解决思路：

1. 清理PATH中的多余Qt bin目录，只保留当前项目使用的版本。
2. 清理build目录，重新qmake并构建，确保所有中间文件都是基于同一个Qt版本生成的。
3. 检查IDE或者命令行里的环境变量（尤其是QMAKE、QTDIR）是否是全局覆盖的。
4. 如果确认环境变量没问题，但运行还是报错，用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 -v

5.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 模块缺失与加载类问题

windeployqt打包这个细节值得多说一句：打包发布时在Qt命令行里执行：

windeployqt 你的程序.exe

它会自动把依赖的DLL和插件目录拷到exe旁边，但对某些附加模块（如Qt Charts、Qt WebEngine）可能不全，生成完毕后建议再用Dependencies.exe扫描一遍，缺什么补什么。

6.2 安装、工具链与开发环境问题

另外，想装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，比看十篇教程都有用。