先聊点实在的。Qt6 是 2020 年底正式发布的跨平台 C 应用框架相比大家更熟悉的 Qt5它在底层做了大量重构渲染架构换成了 RHI图形抽象层QML 引擎重写很多模块也被拆散重组。说白了如果你现在才开始学 Qt或者公司新项目要立项直接上 Qt6 是明智的没必要抱着 Qt5 不撒手。这篇博客就是写给准备装 Qt6、又不想在第一步就栽跟头的人看的。我会把下载渠道、安装组件勾选、环境变量配置、第一个程序跑通以及和 PyCharm 配合使用这些事一步一步讲清楚。这篇内容覆盖两个典型人群一种是纯 C 路线装官方 Qt6 Qt Creator 写桌面应用另一种是想用 Python 调 Qt 做界面也就是走 PySide6Qt for Python的路线。两条路我都会讲到你可以根据自己的底子选一条走也可以先看我怎么说再决定。整个安装过程在 Windows 上演示但 Linux 和 macOS 的差异我也会提一嘴不至于换个系统就抓瞎。1. 下载之前的准备工作先想清楚三件事1.1 版本怎么选在线安装器、离线包、还是第三方编译版很多人第一次接触 Qt会直接去官网点“Download”结果发现官方主推的是在线安装器不是那种一个压缩包解压就能用的东西。这个设计其实有它的道理Qt 的组件非常多把整个套件全下载下来超过 10GB但绝大多数人用到的可能不到三分之一。在线安装器可以按需勾选下载完就能用省时省力。但如果你网络环境不好或者公司内网完全不能访问外网那就得用离线安装包。Qt 官方对离线包的限制比较严格开源版本只能下载最新的补丁版历史版本基本需要商业授权或者登录账号后才能拿。这个逻辑要理解Qt 是商业公司开源版是它的获客入口不可能像 Linux 发行版那样把所有历史 ISO 都挂在 FTP 上任你下载。另外一个现实问题就是下载速度。Qt 官方服务器在海外的速度懂的人都懂。好在国内有几家高校镜像站长期同步 Qt 安装器和离线包最常用的就是清华 TUNA 镜像mirrors.tuna.tsinghua.edu.cn/qt和中国科学技术大学镜像mirrors.ustc.edu.cn/qtproject。我自己的习惯是直接去清华镜像下载离线包或者用在线安装器配合镜像参数。这个后面细说反正记住一条在官网下载卡成狗的时候别硬等换镜像。1.2 编译器选型MSVC 还是 MinGW这是个问题这是新手最容易懵的地方。同样一个 Qt6在 Windows 上官网提供了两套预编译版本MSVC 2022 和 MinGW 11.2.0不同小版本号会变。你选哪一个决定了后面用什么编译器来写代码。MSVC 是微软的编译器对应 Visual Studio 那套生态。如果你想用 CMake 配合 Visual Studio 开发或者需要调用 Windows API 的一些特性建议选 MSVC 版本。注意Qtd 官方 MSVC 包不会自带编译器你必须自己装 Visual Studio 或者 Build Tools否则 Qt Creator 里会提示找不到工具链。MinGW 是 GCC 在 Windows 上的移植版配合 Qt Creator 用最顺因为 Qt 官方 MinGW 压缩包里自带编译器装完就能编译不需要额外再装任何东西。缺点是调试器gdb支持相对弱一些遇到一些奇怪的内存问题排查起来会比 Visual Studio 的调试器麻烦。我的建议是如果你只是想学 Qt、做点小工具选 MinGW如果你在公司要用 Qt 做正式项目选 MSVC因为 MSVC 编译出的程序性能和兼容性通常更好也更容易集成到现有的 Windows 构建体系里。当然你两套都装也没问题同一套源码可以分别用两种编译器构建Qt Creator 的 Kit 机制就是干这个的。1.3 操作系统和磁盘空间别小看这两个前提Qt6 官方支持 Windows 10/11、主流 Linux 发行版Ubuntu、Debian、Fedora 等和 macOS 11 以上的版本。Windows 7 和 8 就别想了Qt6 不支持。磁盘空间这块我建议至少预留 30GB。别觉得夸张你装一个 Qt 6.x 核心库加上 Qt Creator再勾选几个常用模块10GB 到 15GB 就出去了。如果你手滑把所有模块都勾上20GB 都不一定够。这不是危言耸听Qt 每次安装还会带源码包、调试符号、示例代码这些都是吃空间的大户。2. Qt6 下载官网、镜像、在线安装器参数详解2.1 官网下载的正确打开方式打开 Qt 官网qt.io点右上角的 Download页面会引导你选择 Qt Online Installer。这一步它会要你填邮箱、用途、公司等等信息然后才能拿到在线安装器的下载链接。这里有个小坑Qt 官网区分 Open Source开源和 Commercial商业两条线你下载开源版的时候要选清楚别稀里糊涂填了一堆商业版的需求回头邮箱里全是销售邮件。下载完成后你会得到一个名字类似 qt-unified-windows-x64-4.x.x-online.exe 的文件这个就是在线安装器。注意它本身只有几十 MB真正的 Qt 组件是启动后根据你勾选的项再下载的。2.2 镜像源下载清华 TUNA 和 USTC 的使用姿势清华大学镜像的路径是 mirrors.tuna.tsinghua.edu.cn/qt进去之后能找到几个子目录archive/qt/所有历史版本包含离线包和在线安装器official_releases/官方发布的正式版本按版本号和平台组织online/qtsdkrepository/在线仓库配合在线安装器使用的镜像源如果你直接用浏览器下载离线包最省事的方式是进入 archive/qt/6.x.x/ 目录选对应平台的安装文件。比如 6.5.3 版本Windows 下会有 qt-opensource-windows-x86_64-6.5.3.exe 或 qt-opensource-windows-x86_64-6.5.3.zip 这类文件。前者是引导安装器后者是解压即用的绿色版。不过绿色版不建议新手用它缺少环境配置和 Qt Creator 的自动集成后面会遇到一堆莫名其妙的问题。2.3 在线安装器配合镜像源加速如果你还是想用在线安装器又想走镜像源加速可以在启动安装器的时候加上镜像仓库地址参数。Windows 的 cmd 或 PowerShell 里执行qt-unified-windows-x64-4.6.0-online.exe --mirror https://mirrors.tuna.tsinghua.edu.cn/qt这样安装器会优先从清华镜像拉取组件列表和安装包速度比官方源快非常多。注意这个参数在不同版本的安装器上可能略有差异如果提示 mirror 参数无效可以用--repository参数试试qt-unified-windows-x64-4.6.0-online.exe --repository https://mirrors.ustc.edu.cn/qtproject/online/qtsdkrepository/windows_x86_64/root/qt/这里有个细节ustc 镜像的在线仓库路径比较长直接抄我上面的这个 root/qt 路径就行它对应的是默认的 Qt 组件仓库。3. Qt6 安装从账号登录到组件勾选全流程3.1 为什么开源版也必须注册账号很多第一次用 Qt 的人都会问我不是用开源版吗为什么还要注册登录这是 Qt 公司的策略不管开源还是商业版安装器都会要求你登录一个 Qt 账号用来做用户统计和版本验证。注册流程很简单填个邮箱设个密码就行不用付费但这一步绕不过去。在线安装器第一次启动会让你输入账号密码离线包安装器也会在安装过程中要求登录。注意登录界面的“Skip”按钮在开源版里通常是不能用的。别浪费时间找跳过按钮了老老实实注册一个账号以后安装更新还要用。3.2 组件勾选别全选学会“按需分配”进入安装器后你会看到一个组件树这是新手最容易出问题的地方。很多人直接全选然后磁盘被塞满、下载半天、最后发现大部分模块根本用不上。反过来也有不少人只勾了最小集结果编译的时候发现缺头文件又得重新打开安装器补装。我按自己的使用习惯给出一套比较合理的勾选方案Qt 6.5.3或者你下载的对应版本下的核心组件至少要勾选你选择的编译器版本比如 MinGW 11.2.0 64-bit 或者 MSVC 2019 64-bit。这个组件是 Qt 库本身必须选。Additional Libraries按需选择。开发桌面应用的话Qt Charts图表、Qt Data Visualization数据可视化、Qt Multimedia多媒体、Qt WebEngine网页引擎这几个比较常用。不确定要不要的话可以先不勾以后用安装器补装就行。Developer and Designer Tools这里的 Qt Creator 是必选的相当于 Qt 官方 IDE。Qt Design Studio 如果做 QML 界面设计可以装新手暂时用不到。Sources这个是 Qt 源码包大小 1GB 以上平时开发用不到。但如果你想深入看 Qt 内部实现、打断点调试进 Qt 源码那么这个必须勾。安装器支持增量安装也就是说即使你现在漏了几个模块后面随时可以重新运行安装器它会检测已安装的组件然后让你勾选要新增的组件。所以第一遍安装没必要追求面面俱到先装一套能跑起来的配置最重要。3.3 安装路径和目录结构别用中文路径安装路径这个事我多说两句。Qt 对路径中的空格和非英文字符的支持不算好尤其是 MinGW 工具链遇到中文路径偶尔会抽风。建议直接装到 D:\Qt 或者 C:\Qt 这种纯英文路径下。安装完成后目录结构大概是这样的D:\Qt\6.5.3\mingw_64\Qt 6.5.3 的核心库包含头文件、库文件、插件等D:\Qt\Tools\Qt 自带的开发工具包括 Qt Creator、MinGW 工具链、CMake 等D:\Qt\Examples\官方示例代码如果你勾选了示例模块这里会有大量参考代码理解这个结构对以后配置环境变量和排查问题都很有帮助。比如你想知道某个头文件在哪直接到对应版本的 include 目录下找就行。3.4 Linux 和 macOS 上的安装差异Linux 用户如果通过官方安装器安装过程和 Windows 类似但需要给安装器文件添加执行权限chmod x qt-unified-linux-x64-4.6.0-online.run ./qt-unified-linux-x64-4.6.0-online.run另外 Linux 上 Qt 依赖一些系统库比如 libGL、libxkbcommon 等缺了会在运行 Qt Creator 或编译时报各种奇奇怪怪的错误。建议装完系统包后先用 apt/yum 安装常见的依赖库。macOS 用户相对省心官方安装器是 .dmg 包拖进去就能装但需要留意 Apple SiliconM 系列芯片和 Intel 芯片对应的版本选择一般安装器会自动识别。4. 安装完成后的必做配置不然后面全是坑4.1 配置系统环境变量很多教程都会跳过环境变量这一步因为 Qt Creator 会自动定位 Qt 库的位置。但如果你后面要使用命令行编译尤其是配合 CMake或者运行自己编译的程序时系统提示“找不到 Qt6Core.dll”就说明环境变量没配好。右键“此电脑” - 属性 - 高级系统设置 - 环境变量新建一个变量变量名QTDIR变量值D:\Qt\6.5.3\mingw_64然后在 Path 变量中追加%QTDIR%\bin。这个 bin 目录里有 Qt6Core.dll、Qt6Gui.dll 这些动态库以及 windeployqt、moc、uic 等开发工具。配置好之后打开一个新的命令行窗口输入qmake --version如果能正常输出版本信息就说明环境变量配置成功了。qmake 是 Qt 的构建工具之一老项目常用它来生成 MakefileQt6 虽然主推 CMake但 qmake 仍然保留着很多教程里也会用到。4.2 Qt Creator 的第一个 Kit 检查打开 Qt Creator进入“工具”-“选项”-“Kits”页面。Kits套件这个概念要理解它把编译器、调试器、Qt 库版本绑定在一起决定你用什么工具链来构建和运行程序。如果你完成了标准安装这里应该已经自动识别并创建了一个默认 Kit比如 “Qt 6.5.3 MinGW 64-bit”。确保这个 Kit 前面的警告图标是正常的。如果显示黄色感叹号通常是编译器或调试器缺失MinGW Kit 缺编译器到 Qt 安装目录下的 Tools/mingw*_64/bin 里找 gcc.exe 和 g.exe手动指定。MSVC Kit 缺调试器安装 Visual Studio 的 Debugging Tools for Windows 组件或者在选项里指定 Windows SDK 自带的 cdb.exe。缺 cmakeQt Tools 里通常自带 CMake检查一下 Kit 页面里 CMake 路径是否有效。这个步骤看起来不起眼但很多“Qt Creator 无法编译”的报错根因就是 Kit 没配好。4.3 跑通第一个 Qt Widgets 程序配置完成后用 Qt Creator 新建一个项目快速验证整个链路是否正常。操作路径文件 - 新建项目 - Application (Qt Widgets) - Choose。填好项目名称和保存路径编译套件选择刚刚确认过的 Kit然后一路下一步生成一个带窗口的模板程序。点击左下角的绿色三角按钮运行应该弹出一个空白的窗口。看到这个窗口你的 Qt6 开发环境就算正式打通了。这里提一个写作编译的小细节Qt6 默认的构建系统是 CMake生成的构建目录和源码目录是分离的。如果后面你在源码目录里找不到编译产物别慌去项目构建目录下的 debug 或 release 文件夹里找 exe 文件。5. 给 Python 用户PySide6 安装与 PyCharm 联动5.1 PySide6 和 PyQt6 怎么选如果你不想写 C而是想用 Python 做界面那么官方路线是 PySide6Qt for Python。它和 PyQt6 功能上非常相似但授权协议不同PySide6 是 LGPL对商业应用更友好PyQt6 是 GPL 商业双协议公司商用有版权风险。新手我建议直接用 PySide6和 Qt 官方同步更新示例代码也最多。5.2 在 PyCharm 里安装和验证 PySide6打开 PyCharm在终端里执行pip install pyside6这个过程会自动拉取 PySide6 的核心库、Qt 工具集和 shiboken6 绑定层。装完后写一个最简单的窗口脚本验证import sys from PySide6.QtWidgets import QApplication, QLabel app QApplication(sys.argv) label QLabel(Hello Qt6 from Python) label.show() sys.exit(app.exec())在 PyCharm 里直接运行应该能看到一个显示文字的标签窗口。如果运行时提示找不到 PySide6 模块检查一下当前解释器是否选的是你刚才安装包的那个 Python 环境这是 PyCharm 新手最常见的坑。5.3 在 PyCharm 中启动 Qt Designer 和工具链除了写代码PySide6 还会安装 Qt Designer 可视化界面设计器。在 PyCharm 的终端里执行pyside6-designer就能打开界面设计器拖拽控件生成 .ui 文件。之后可以用 pyside6-uic 工具把 .ui 文件转换成 Python 代码pyside6-uic mainwindow.ui -o ui_mainwindow.py在 PyCharm 里你可以把这三个工具配成外部工具Settings - Tools - External Tools这样以后右键点击 .ui 文件就能直接打开设计器编辑完一步转换不用总是敲命令行。配置的时候要注意 Program 路径指向你 Python 环境下的 Scripts 目录比如 C:\Python312\Scripts\pyside6-designer.exe。5.4 PySide6 和 C Qt6 的关系这里有个很多 Python 用户会困惑的点PySide6 的 API 和 C 版 Qt6 几乎是镜像关系。C 里的 QApplication、QLabel、QPushButton 这些类在 PySide6 里名字完全一样只是写法从-变成了点号。这意味着你学 PySide6 积累的 Qt 知识以后如果转 C Qt迁移成本很低反过来也一样。所以无论是走 C 路线还是 Python 路线核心要学的是 Qt 的对象模型、信号槽机制、布局管理和 QML 渲染这套东西语言只是外壳。6. 常见问题与排查技巧实录6.1 下载慢、卡 0%、安装器直接退出这是国内用户遇到最多的问题几乎都是网络原因。解决办法优先使用镜像源。在线安装器可以带上--mirror参数启动如果安装器已经打开可以在设置中临时修改仓库地址为清华镜像。另外关掉系统代理或者换个网络环境比如从宽带换到手机热点有时候也能解决问题。如果你用的是离线包直接去清华镜像的 archive/qt 目录下载对应文件绕过官方服务器。6.2 编译报错找不到 QApplication 头文件错误信息类似fatal error: QApplication: No such file or directory。这个问题的原因通常是项目没有正确链接 Qt 模块。在 CMakeLists.txt 中检查是否用了find_package(Qt6 REQUIRED COMPONENTS Widgets)并且target_link_libraries里链接了 Qt6::Widgets。Qt 的头文件和库是按模块组织的光安装了 Qt 基础库但不链接对应模块编译时一样找不到头文件。6.3 Qt Creator 里 Kit 显示黄色感叹号前面提到过最常见原因是编译器或调试器路径无效。到“工具”-“选项”-“Kits”里把编译器、调试器、CMake 几个子项都点开检查一遍。如果编译器列表为空手动添加MinGW 的 g 在 Qt 安装目录的 Tools/mingw*/bin 下MSVC 的编译器则需要在安装了 Visual Studio Build Tools 之后才能被识别。还有一个冷门原因如果你装了多个版本的 Qt 和多个编译器Kit 配置容易串建议把不用的 Kit 删掉保留一个最顺手的。6.4 运行时提示“无法定位程序输入点”或缺少 DLL这种错误分两类。一类是“找不到 Qt6Core.dll”说明程序运行时没有找到 Qt 库的路径把 Qt 的 bin 目录加进 Path或者用 Qt Creator 直接运行都能解决。另一类是“无法定位程序输入点……于动态链接库……”这类奇怪报错多数是系统 PATH 里存在多个版本的 Qt 动态库程序加载了错误的 DLL。检查一下 Path 里是否有旧版本 Qt 的 bin 路径如果有把它挪到新版本之后或者直接删除。这种新旧版本 DLL 混用的问题特别阴因为报错信息不会直接告诉你它加载了哪个 DLL你只能用 Process Explorer 这类工具查看加载到进程里的 DLL 路径。6.5 中文乱码问题Qt6 在 Windows 上处理 UTF-8 字符串有了改进但乱码问题依然存在。在源码文件中建议源文件编码统一用 UTF-8。在 MSVC 编译器下可以在 CMakeLists.txt 里加上add_compile_options($$CXX_COMPILER_ID:MSVC:/utf-8)这会告诉 MSVC 把源文件按 UTF-8 解析。如果用的是 MinGW一般默认 UTF-8 就行问题不大。6.6 编译很慢怎么办Qt 项目编译慢尤其是第一次全量编译的时候几分钟到十几分钟都是正常的。可以通过几个方式加速使用 Ninja 替代默认的 Makefiles 生成器Qt Creator 在新建 CMake 项目时可以选择 Generator开启 Qt Creator 的“JOM”或并行编译参数把 Qt 库的调试符号去掉Release 模式下。另外如果你是 MSVC 工具链确保安装了“Windows 11 SDK”而不是老版本 SDK新版 SDK 对编译速度有优化。7. 我个人踩坑后的真实建议装完 Qt6 到现在我用它写过几个内部工具和原型项目整体体验比 Qt5 时代清爽不少但安装这一步确实劝退了不少人。总结几条走心建议给你。第一条安装时别一味追新版本。Qt 每半年左右会出一个新版本但没必要第一时间升级。选一个稳定的 LTS长期支持版本用上半年比如 Qt 6.5 LTS 或者之后的 6.8 LTS优先用 LTS因为社区反馈多、坑都被填得差不多了网上搜得到的问题解法也多。新版本刚出的时候第三方模块可能还没来得及适配你会被迫在“用新特性”和“用稳定库”之间做选择。第二条环境变量和 Kit 配置值得花十分钟一步到位。我当时就是懒得配环境变量结果用命令行跑 CMake 构建时频繁找不到 Qt 库来来回回浪费了一个晚上。Qt Creator 确实能自动识别但你迟早会用到命令行构建或者写脚本做自动化编译环境变量这一步逃不掉。第三条如果你用 Python 做 Qt 开发把 C 版的官方文档当参考也是完全可行的。Qt 官方文档里大部分类都有 Python 示例连 PySide6 专属的章节也有。遇到问题先搜Qt 类名 PySide6通常能找到现成代码。不要因为自己用 Python 就觉得 C 资料和自己无关Qt 的很多概念和模式在不同语言绑定里是通用的。第四条关于调试器。Windows 上如果你用 MinGW 套件默认的 gdb 调试体验一般遇到复杂的变量监视时可能没法正确显示 STL 容器内容。在自己可控的情况下公司项目尽量用 MSVC 工具链调试体验会好一大截个人学习无所谓能跑起来就行。最后再分享一个小技巧Qt 安装目录下有一个 Maintenancetool.exe双击它可以随时“添加或移除组件”。我经常用它来补装模块比如一开始没勾 Qt Charts后来画图表了直接打开这个工具勾选 Qt Charts 组件几分钟装完不需要重装整个 Qt。很多人折腾了半天最后发现这个工具的存在感慨自己白装了三遍 Qt。
