企业官网建设流程全解析

1. 别纠结了，Qt 6 开源版就得这么装

如果你现在打开搜索引擎搜“Qt 6 免费开源版本在线安装教程”，大概率是因为在官网下载页被那两三个入口绕晕了，或者装到一半发现缺东少西开始怀疑人生。我先说结论：Qt 6 开源版现在的主流安装方式就是通过官方在线安装器来做，它不是一个完整的离线安装包，而是一个带图形界面的引导程序，你选什么组件它就现场去拉什么。对于绝大多数 C++ 开发者、Qt 初学者、以及从 Qt 5 往 Qt 6 迁移的老工程来说，这套流程都是最省事、最不容易出错的路子。

这篇文章我会把这套在线安装流程从头到脚拆开揉碎讲清楚，包括为什么官方主推在线安装、装之前要准备什么、每一步点哪里、常见坑怎么避，最后再补一份高频问题速查表。内容不搞虚的，全是我实际踩过、试过、验证过的东西，照着做基本能一把过。

准备工作先说结论：一个 Qt 账号、一个网络稳定的时间段、一块至少 20GB 空闲的硬盘，只要你把这些备齐，剩下的就是对着本文点点点。整个过程大概二十分钟到一小时，取决于你选了多少组件、网络吞吐如何。装完之后你会得到一个 Qt Creator 集成开发环境、一套编译器工具链，以及一系列跨平台开发模块，后面做桌面软件、写个小工具、跑嵌入式界面都不成问题。

2. 为什么官方主推在线安装，离线包反而不好用

2.1 Qt 6 时代安装方式的演变

用过 Qt 5 的人应该还有印象，那时候官网会直接放出类似 qt-opensource-windows-x86-5.14.2.exe 这种动辄 2GB 到 3GB 的离线安装包，下载下来之后断网都能装。到了 Qt 6 时代，官方策略明显变了——不再提供完整离线安装包，取而代之的是一个体积只有几十 MB 的 qt-online-installer。你运行它，登录账号，勾选需要的模块，然后它实时下载并解压到你指定的目录。

为什么会这样？最直接的原因是 Qt 6 的模块划分比 Qt 5 更细。同样一个版本，你既可以选择只装基础 GUI 模块，也可以额外塞进 Charts、Data Visualization、WebEngine、Multimedia 等扩展模块。如果继续提供全量离线包，体积会膨胀到让人劝退，而在线安装器可以根据你的实际需求按需拉取，磁盘占用和下载流量都更可控。

另外一个更实际的原因是维护成本。Qt 6 的发版节奏比 Qt 5 快不少，社区补丁和小版本更新也更频繁。离线包一旦发出去，修复 bug 就得重新打一个好几个 GB 的包；在线安装器则可以在后续小版本里做增量更新，官方省事，用户也省流量。

2.2 在线安装与离线安装的取舍

我知道你可能会犹豫：在线安装是不是就一定更好？我把两种方式放在一起对比一下：

结论很清楚：在新项目、新环境下，官方在线安装器是更合理的选择。唯一需要提醒的是，如果你所在环境下载速度不稳定，建议挑网络平稳的时段来操作，或者错峰安装，别在高峰期硬冲，否则中途下载失败的概率会明显上升。

注意：Qt 6 官方不再为普通用户提供离线开源安装包，所谓“离线包”大多来自第三方整包或旧版 Qt 5 资源。为了安全性和版本可溯源性，建议遵循官方在线安装流程，不要轻信来源不明的整包。

3. 安装前的准备工作

3.1 注册 Qt 账号与开源协议说明

在线安装的第一步并不是下载安装器，而是准备一个 Qt 账号，因为安装器启动后第一步就是让你登录。这个账号在 qtlogin 页面免费注册，填邮箱、设密码就能搞定，不需要付费，也不绑定什么试用期。它的作用有两个：一是记录你的许可选择，二是关联你以后可能用到的 Qt 官方服务。

注册时需要注意，邮箱要填能正常收信的，因为账号验证会发送一封确认邮件。我用过 QQ 邮箱、163 邮箱和 Gmail 都能正常收到，一般在几分钟内到达，偶尔会有延迟，等不及就过几分钟刷新一下。

说到开源协议，这是很多新手容易忽略的地方。Qt 6 开源版基于 LGPLv3 或 GPLv2/GPLv3 双许可发布，具体来说是：自 Qt 6.0 起，开源版默认采用 LGPLv3，同时保留 GPLv2 作为备选。LGPL 的意思是，你可以把 Qt 当作动态链接库用在闭源商业软件里，但如果你修改了 Qt 源码本身并动态链接使用，对应修改部分需要开源；如果用静态链接，那整个程序在分发时可能需要提供可被替换的 Qt 对象文件。GPL 则更严格，只要你的程序链接了 GPL 代码，整个程序原则上都要以 GPL 方式开源。

所以，如果你做的是内部工具、开源项目、学习实验，直接用开源版没问题。如果你要给客户交付闭源商业软件，而且涉及静态链接或者需要深度修改 Qt 源码，那就要认真评估是否购买商业许可。商业版有专人技术支持、可以合法闭源静态链接，还附带一些开源版没有的组件，比如 Qt for MCU 的部分能力。

3.2 确定你要装哪个版本

打开在线安装器之后，你会看到一长串 Qt 版本列表。光是 6.x 系列就可能有 6.5、6.6、6.7、6.8 等好几个发行版本，旁边还可能标注 LTS 字样。LTS 是 Long Term Support 的意思，表示长期支持版本，官方承诺更长的维护周期，适合用于生产环境和需要长期稳定的项目。

我的建议是：不做特殊研究就选 LTS 版本。当前阶段最优解通常是最新的 LTS 大版本，例如 6.8 LTS 或者官方已经标注 LTS 的最新版本。如果你是从 Qt 5.15 迁移过来的老工程，重点看你要用的模块在新版本里是否保留、接口是否有 breaking change。Qt 6 对 C++17 的支持是默认开启的，对老编译器的兼容性不如 Qt 5 好，所以如果你还在用远古 GCC 或者老版本 MSVC，先升级编译器再换 Qt 6 更稳妥。

同期还会有一个"最新开发版"或者"预览版"选项，除非你要给官方提 bug 或者极其追求新特性，否则不建议在生产环境装。开发版稳定性说不准，我见过有人装预览版做毕业设计，结果某次更新后编译直接崩，排查了半天才发现是预览版的问题，教训很惨痛。

3.3 获取 Qt 在线安装器

获取安装器的官方入口在 Qt 官网的下载页面，页面分两个选项：一个是商业版，一个是开源版。选了开源版之后，系统会让你确认是否接受开源协议条款，然后才会显示实际下载链接。下载文件通常叫 qt-online-installer-windows-x64-xxxx.exe，Windows 对应 exe，Linux 对应 .run，macOS 对应 .dmg。

下载完成后，文件很小，一般也就几十 MB。不需要额外解压，直接双击执行。如果你在 Linux 下拿到的是 .run 文件，记得先给它加执行权限，命令是：

chmod +x qt-online-installer-linux-x64-xxx.run ./qt-online-installer-linux-x64-xxx.run

否则直接双击多半没反应，终端还会提示 Permission denied，第一次用 Linux 的人很容易在这里卡住。

3.4 磁盘空间和系统环境检查

安装器本身不大，但装完 Qt 6 完整开发环境后占用空间会明显膨胀。我实测一个包含 Qt Creator、MinGW、基础 Qt 模块、调试工具的最小配置大约要 6GB 到 8GB；如果你把常用的扩展模块也勾上，比如 Charts、Multimedia、NetworkAuth、WebEngine，奔着 15GB 到 25GB 去很正常。

所以装之前先看看你的系统盘剩余空间，别挤在 C 盘装了一半按不下去。安装目录建议改名放在根目录，比如 D:\Qt 或者 /opt/Qt，尽量不要包含空格和非英文字符，虽然现在 Qt 对空格路径兼容性好了不少，但某些第三方插件和老脚本仍然会在含空格的路径上出问题，能免则免。

系统环境方面，Windows 用户要确保系统补丁更新到较新状态，尤其是那些还在用 Windows 7 的家庭用户——注意，Qt 6 官方已经明确不再支持 Windows 7，如果你的机器还是 Win7，老老实实用 Qt 5.15 或者升级系统。Linux 用户则要确认装了基础编译依赖，比如 build-essential、libgl1-mesa-dev、libxkbcommon-x11-dev 等，否则 Qt 装上了也起不来。macOS 用户需要保证系统版本不低于官方文档要求，同时 Xcode Command Line Tools 要装好。

4. 在线安装完整操作步骤

4.1 启动安装器与登录账号

双击安装器之后，首先映入眼帘的是欢迎页和许可选择界面。这里会再次问你用商业许可还是开源许可，选开源许可后系统会要求你登录刚才注册的 Qt 账号。

这里有个细节：登录页面会显示用户名和密码两个框，下面还有一个"我同意隐私政策"的勾选项。不勾这个复选框，登录按钮是置灰的，很多人会漏看这一行，以为是网络卡了。我第一次装 Qt 6 的时候也栽在这里，盯着界面看了半分钟才反应过来。

登录完成后，安装器会显示欢迎页，通常是一个简短的介绍和"Next"按钮。接下来会让你选择安装路径，也就是 Qt 库的最终存放位置。默认路径在 Windows 下是 C:\Qt，在 Linux 下是 /home/用户名/Qt。我个人习惯改成 D:\Qt 或者 /opt/Qt，主要是为了重装系统不丢环境、C 盘空间也好控制。

4.2 组件选择的思路与方法

安装器的组件选择界面是核心环节，也是新手最容易蒙圈的地方。界面左侧是一棵组件树，按大版本展开，每个大版本下面会分多个子项。以 Qt 6.8 LTS 为例，展开后大概长这样：

• Qt 6.8 LTS
  • 附加组件
  • 附加库
  • Qt Debug 信息文件
  • Qt Creator 插件
• Qt 6.8.0
  • MSVC 2019 64-bit
  • MinGW 11.2.0 64-bit
  • Sources
  • UWP x64 / x86
• 开发工具
  • Qt Creator
  • CMake
  • Ninja
  • MinGW 11.2.0
  • 调试工具

这里要懂几个概念。Qt 6 默认构建系统已经切换到 CMake，所以开发工具里的 CMake 和 Ninja 基本是必装的。编译器套件决定你最终能用哪个 Kit 来编译代码，Windows 下常见两个选择：MSVC 和 MinGW。

MSVC 是微软的编译器，通常在 Visual Studio 里自带，Qt 模块里的 MSVC 版本要和 Visual Studio 的版本匹配，比如 MSVC 2019 对应 VS2019，MSVC 2022 对应 VS2022。MinGW 是 GCC 在 Windows 下的移植版，和 Visual Studio 无关，装完独立可用。如果你不打算装 Visual Studio，那就在开发工具里勾选 MinGW，然后在 Qt 模块里也勾选对应版本的 MinGW 编译器，这样 Qt Creator 就能直接识别并组成一个可用的 Kit。

那到底选 MSVC 还是 MinGW？我的经验是：做长期项目、要调 Windows API、要接微软生态的库，优先 MSVC，因为很多第三方库在 Windows 下默认只编译 MSVC 版本；如果只是学习、写小工具、不想装庞大的 VS，MinGW 够用且更轻便。两者不要贪多全选，毕竟每个编译器对应的 Qt 库都要占一份磁盘空间，全选意味着体积翻倍。

模块层面，默认勾选的一般包含 Qt 5 Compatibility Module、Qt Quick 等基础模块。除此之外，日常开发里我用得比较多的还有这些：

• Charts：画折线图、柱状图、饼图
• Data Visualization：3D 数据可视化
• Multimedia：音视频播放、录音
• NetworkAuth：OAuth 登录流程
• WebEngine：内嵌 Chromium 浏览器
• SerialPort：串口通信
• Positioning / Location：定位位置服务
• WebSockets：WebSocket 通信

如果你确认项目里不会用某个模块，就别勾。模块装多了不仅占空间，还会让 Qt Creator 的索引速度变慢，尤其是第一次构建工程时，全模块的元对象编译器遍历会明显卡顿。学习阶段建议先装基础模块加 Charts、Multimedia、SerialPort，后面用到再加都可以。

4.3 确认许可并开始安装

组件选完之后，安装器会让你确认许可协议，这里默认是 LGPLv3 条款。你需要勾选"我已阅读并同意"才能进入下一步。注意此处并不是走过场，如果你在后续分发软件时违反了 LGPL 条款，是存在法律风险的，所以至少花几分钟扫一眼协议大意。

接下来是最终确认界面，会列出你选择的版本、组件数量、预计下载大小和所需磁盘空间。重点看两个数字：第一个是下载大小，第二个是安装后占用大小。如果后者远大于你的剩余空间，赶紧返回上一步去掉不必要的组件。

点击"Install"之后，安装器开始下载安装包并自动解压。这个过程比较漫长，进度条会卡在某几个大模块上很久，尤其是 WebEngine 这种动不动几百 MB 的组件。这时候别去动安装过程，也尽量不要切到别的任务狂占带宽，否则下载失败的概率会提升。如果下载中断，安装器一般会提示重试，不要慌，重试通常能续上。

装完之后，安装器会提示你启动 Qt Creator 还是直接退出。我建议首次先启动一下 Qt Creator，确认它能正常打开、能识别到你刚才安装的 Kit。如果你没装任何编译器，Qt Creator 启动后会在 Kit 页面提示“未找到编译器”，这时候退回安装器补装编译器，或者去装 Visual Studio Build Tools，别硬着头皮往下写代码。

4.4 验证安装：跑一个最简单的窗口程序

安装完成不代表环境就是好的，我强烈建议你立刻跑一个最简单的小例程，验证整个链路通不通。打开 Qt Creator，新建项目，选择“Qt Widgets Application”，编译器 Kit 选择你刚装好的那套。默认会生成一个带空窗口的模板，直接点运行按钮。

如果能弹出一个空标题的窗口，恭喜你，安装链路基本没问题。如果编译报错，优先看错误信息里有没有提到编译器版本不匹配、找不到 Qt 头文件、找不到链接库这三类问题。大多数情况下，报错原因都在 Kit 配置不对——要么选错了 Kit，要么编译器路径没配置好，往下看到常见问题的部分就能找到对应解法。

在 Windows 上还有一个非常容易翻车的点：如果你同时装了 MinGW 和 MSVC 两个 Kit，然后新建项目时默认选了其中一个，代码里用了另一个编译器才能用的第三方库，链接阶段就会报一堆 LNK2019 或者 undefined reference。这个不是 Qt 的问题，是你 Kit 和库没对齐。

5. 常用维护操作：增量安装组件与彻底卸载

5.1 用 MaintenanceTool 增删组件

Qt 在线安装器在安装完成之后，会在安装根目录生成一个叫 MaintenanceTool.exe 的程序，Windows 下在安装目录根下，Linux 下对应 MaintenanceTool 可执行文件。这个工具是你日后维护 Qt 环境的总入口，功能包括：添加或移除组件、更新组件、卸载整个 Qt。

比如你在开发过程中发现项目需要 SerialPort 模块，但装 Qt 的时候没勾。没必要重装整个 Qt，直接运行 MaintenanceTool，选择“添加或移除组件”，找到你的 Qt 版本，勾上 SerialPort，点下一步，它会自动增量下载并安装。整个操作和首次安装的组件选择界面基本一样，非常方便。

更新同理。Qt 官方会不定期发布补丁版本，你可以在 MaintenanceTool 里选择“更新组件”，它会列出当前已安装版本可升级的补丁包。由于 Qt 6 小版本更新偶尔会引入 ABI 变化或行为变化，升级前建议看一眼更新说明，别在项目交付前两天顺手点了个升级结果把接口改崩了。

5.2 卸载 Qt 的正确打开方式

卸载 Qt 也不要直接删除文件夹。虽然删目录看起来干净，但会留下注册表项和残留的工程配置，以后重装可能出现诡异问题。正确做法同样是使用 MaintenanceTool，选择“删除所有组件”或者“移除单个组件”，它会完整地做清理。

在实际项目中，我见过有人因为 Qt Creator 缓存异常，直接把整个 Qt 目录手动删除想重新装，结果新装的 Qt Creator 一打开就报 "Qt version is not properly installed"，最后折腾半天才发现旧的注册表信息还在。用官方卸载工具就能完全避免这类问题。

如果你只是想清理 Qt Creator 的缓存配置而不动 Qt 库本身，那和卸载无关，需要清的是用户目录下的 .config/QtProject 和 .cache/Qt 相关目录。这类缓存异常一般表现为工程列表丢失、Kit 列表错乱、启动卡死，清缓存目录后重启 Qt Creator 即可恢复。

6. 高频问题排查与实战避坑

6.1 老生常谈：Unknown module(s) in Qt: serialport

这个问题在我搜索热词里占了非常高的热度，实际遇到的人确实不少。报错信息通常长这样：

:-1: error: Unknown module(s) in QT: serialport

出现这个错误的原因非常简单：你的工程文件 .pro 里写了 QT += serialport，但当前选择的 Kit 对应的 Qt 库里没有安装 SerialPort 模块。绝大多数情况下，不是代码问题，纯粹是组件没装齐。

解决办法就是回到 MaintenanceTool，选择“添加或移除组件”，展开对应 Qt 版本，找到 SerialPort 模块并勾选，然后增量安装。装完之后回到 Qt Creator，确保 Tools -> Options -> Kits 里边选择的 Qt 版本是装好模块的那个版本，重新构建即可。SerialPort 模块并不是默认随 Qt 一起安装的，这一点很多教程没说透，所以新手特别容易踩。

6.2 cannot mix incompatible Qt library：版本指纹不匹配

还有一个高频报错是：

cannot mix incompatible Qt library (5.15.3) with this library (5.15.2)

这个错误说的是两段 Qt 库版本不一致，一处是 5.15.3，另一处是 5.15.2，两边对不上，链接器拒绝继续工作。这种情况几乎都是因为环境里同时存在多个 Qt 版本，或者程序运行时动态库搜索路径里混进了不同版本。解决思路很直接：确保编译时用的 Qt 头和运行时用的 Qt 动态库是同一个版本。

具体操作上，第一步检查 PATH 环境变量里有没有早期 Qt 的 bin 目录；第二步检查项目里 LIBS 和 INCLUDEPATH 是否手动指向了错误的 Qt 路径；第三步用 Process Explorer 或者 ldd 看进程实际加载的 Qt DLL 是哪一个。很多时候是因为用 Qt Creator 打开旧工程，工程文件里硬编码了旧版本路径，改回来就好。

6.3 一切就绪但 Kit 列表为空或显示无效

装完组件后打开 Qt Creator，Tools -> Options -> Kits 里可能显示 "No compiler set in kit" 或 "Qt version invalid" 之类的提示。这通常是因为安装 Qt 时没有勾选对应的编译器，或者编译器检测失败。

Windows 下如果选了 MSVC 套件，但机器上没装 Visual Studio 或 Build Tools 对应版本，Kit 就会无效。解决办法是安装 Visual Studio 的 C++ 桌面开发组件，然后重启 Qt Creator，让它重新检测。如果选了 MinGW，则确认安装器里 “开发工具” 分类下的 MinGW 编译器被打勾了，因为 Qt 库和编译器是分开安装的，只装库不装编译器就会出现 Kit 无效。

一个很容易踩的坑是：Qt Creator 对 MSVC 的检测依赖注册表，如果你装了绿色版或者社区版，有时候检测不完整。这时候你应该在 Kits 界面手动指定编译器和调试器路径，别指望自动检测全自动搞定。

6.4 卸载残留与环境变量冲突

卸载 Qt 之后，如果你还在 PATH 里留着旧 Qt 的 bin 目录，那么你安装新版本时很有可能会在运行阶段加载到旧版本的 DLL，表现就是程序能编译但启动就崩溃，或者编译时莫名其妙找不到头文件。这个问题在 Windows 上尤其常见。

排查方法是在终端执行 where qmake 或者 which qmake，看实际调用的是哪个路径。如果显示的是你已经卸载掉的旧目录，说明 PATH 里有残留。打开系统环境变量编辑，把旧 Qt 相关的 bin 路径清理掉，重新打开终端再验证一次。

6.5 打包发布相关的基础认知

很多人在装好 Qt、写完程序之后，会直接拿 exe 发给别人，结果对方电脑上运行时报"缺少 Qt6Core.dll"。这是因为 Qt 不是静态库，运行需要依赖一堆 Qt 动态库。发布前需要在 Qt 安装目录的 bin 下找到 windeployqt 工具，用它把依赖拷到你的程序目录。Qt 6 的 windeployqt 一般不用手动指定 Qt 路径，安装好的环境里它会自动匹配当前编译工具的 Qt 库。

基础用法是在源码构建目录下执行：

windeployqt MyApp.exe

执行后会自动拷贝程序依赖的 Qt DLL、平台插件、样式插件等。如果你用了 WebEngine 这种大件，生成目录体积会非常可观，这是正常现象。发布包比开发环境小得多，但比单 exe 大很多是 Qt 程序的常态，想压小只能考虑静态编译或者换其他技术栈，那是另一个话题了。

6.6 高频问题速查表

6.7 个人使用习惯建议

装完环境之后，我习惯在本地随手建一个文本文件，记下当前机器上装了哪些 Qt 版本、对应哪个 Kit、用的编译器是什么、主要跑哪些项目。这个习惯看起来土，但在同时维护两三个 Qt 环境的时候非常救命，尤其是隔了几个月回来继续写老项目，如果没有记录，你可能连“这项目是用哪个 Kit 跑的”都想不起来。

另外建议定期用 MaintenanceTool 检查更新，但不要一有更新就立刻升级。我的原则是：个人学习项目可以追新，有交付压力的项目全部锁定版本，等一个迭代窗口稳定后再评估是否升级。Qt 更新虽然大体兼容，但 C++ 项目靠手工改接口的成本很多时候比想象中高。

最后再说一个小技巧：如果你经常在多个 Qt 版本之间切换，建议不要把所有版本都勾到同一个 Qt Creator 里，而是为每个主要项目单独建一个快捷方式参数，或者干脆为不同的 Qt 版本单独装一份 Qt Creator。虽然官方说支持多版本共存，但索引、缓存和构建目录偶尔会互相干扰，分开更省心。