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 5 时代常见首次下载体积小先下载引导程序即可大全量包动辄数 GB组件选择灵活度高按需勾选模块低只能整体装或整体不装后续维护可增量更新、增删组件需重新下载完整包对网络依赖强整个安装过程都需要网络弱下载完成后可断网安装磁盘占用可控只装需要的较高包含大量用不上的模块安装器本身体积小启动快大文件校验时间长结论很清楚在新项目、新环境下官方在线安装器是更合理的选择。唯一需要提醒的是如果你所在环境下载速度不稳定建议挑网络平稳的时段来操作或者错峰安装别在高峰期硬冲否则中途下载失败的概率会明显上升。注意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 对 C17 的支持是默认开启的对老编译器的兼容性不如 Qt 5 好所以如果你还在用远古 GCC 或者老版本 MSVC先升级编译器再换 Qt 6 更稳妥。同期还会有一个最新开发版或者预览版选项除非你要给官方提 bug 或者极其追求新特性否则不建议在生产环境装。开发版稳定性说不准我见过有人装预览版做毕业设计结果某次更新后编译直接崩排查了半天才发现是预览版的问题教训很惨痛。3.3 获取 Qt 在线安装器获取安装器的官方入口在 Qt 官网的下载页面页面分两个选项一个是商业版一个是开源版。选了开源版之后系统会让你确认是否接受开源协议条款然后才会显示实际下载链接。下载文件通常叫 qt-online-installer-windows-x64-xxxx.exeWindows 对应 exeLinux 对应 .runmacOS 对应 .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.0MSVC 2019 64-bitMinGW 11.2.0 64-bitSourcesUWP x64 / x86开发工具Qt CreatorCMakeNinjaMinGW 11.2.0调试工具这里要懂几个概念。Qt 6 默认构建系统已经切换到 CMake所以开发工具里的 CMake 和 Ninja 基本是必装的。编译器套件决定你最终能用哪个 Kit 来编译代码Windows 下常见两个选择MSVC 和 MinGW。MSVC 是微软的编译器通常在 Visual Studio 里自带Qt 模块里的 MSVC 版本要和 Visual Studio 的版本匹配比如 MSVC 2019 对应 VS2019MSVC 2022 对应 VS2022。MinGW 是 GCC 在 Windows 下的移植版和 Visual Studio 无关装完独立可用。如果你不打算装 Visual Studio那就在开发工具里勾选 MinGW然后在 Qt 模块里也勾选对应版本的 MinGW 编译器这样 Qt Creator 就能直接识别并组成一个可用的 Kit。那到底选 MSVC 还是 MinGW我的经验是做长期项目、要调 Windows API、要接微软生态的库优先 MSVC因为很多第三方库在 Windows 下默认只编译 MSVC 版本如果只是学习、写小工具、不想装庞大的 VSMinGW 够用且更轻便。两者不要贪多全选毕竟每个编译器对应的 Qt 库都要占一份磁盘空间全选意味着体积翻倍。模块层面默认勾选的一般包含 Qt 5 Compatibility Module、Qt Quick 等基础模块。除此之外日常开发里我用得比较多的还有这些Charts画折线图、柱状图、饼图Data Visualization3D 数据可视化Multimedia音视频播放、录音NetworkAuthOAuth 登录流程WebEngine内嵌 Chromium 浏览器SerialPort串口通信Positioning / Location定位位置服务WebSocketsWebSocket 通信如果你确认项目里不会用某个模块就别勾。模块装多了不仅占空间还会让 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 CreatorTools - 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 高频问题速查表问题现象常见原因解决方式报错 Unknown module(s) in Qt对应模块未安装MaintenanceTool 增量安装对应模块cannot mix incompatible Qt library多版本 Qt 混用检查 PATH、LIBS、编译头文件路径统一版本Kit 无效或编译器列表为空未安装匹配编译器安装 MSVC 对应 VS 组件或补装 MinGWqmake 指向旧版本PATH 残留清理 PATH 中的旧 Qt bin 路径程序在别人电脑上缺少 DLL未做发布部署用 windeployqt 拷贝依赖运行崩溃但编译正常DLL 加载版本冲突检查进程实际加载的 Qt DLL 路径安装中途下载失败网络波动错峰重新安装重试即可更新后旧项目编译不过小版本引入行为变化查看更新说明回退版本或调整代码6.7 个人使用习惯建议装完环境之后我习惯在本地随手建一个文本文件记下当前机器上装了哪些 Qt 版本、对应哪个 Kit、用的编译器是什么、主要跑哪些项目。这个习惯看起来土但在同时维护两三个 Qt 环境的时候非常救命尤其是隔了几个月回来继续写老项目如果没有记录你可能连“这项目是用哪个 Kit 跑的”都想不起来。另外建议定期用 MaintenanceTool 检查更新但不要一有更新就立刻升级。我的原则是个人学习项目可以追新有交付压力的项目全部锁定版本等一个迭代窗口稳定后再评估是否升级。Qt 更新虽然大体兼容但 C 项目靠手工改接口的成本很多时候比想象中高。最后再说一个小技巧如果你经常在多个 Qt 版本之间切换建议不要把所有版本都勾到同一个 Qt Creator 里而是为每个主要项目单独建一个快捷方式参数或者干脆为不同的 Qt 版本单独装一份 Qt Creator。虽然官方说支持多版本共存但索引、缓存和构建目录偶尔会互相干扰分开更省心。