上个星期帮团队里新来的同学配置 Qt Creator，他照着网上一份老教程走，结果卡在登录那一步半天没弄明白。这事其实不怪他——新版本的 Qt Creator 安装配置，跟以前那种“下载离线包、一路下一步、装完就用”的流程相比，变化已经非常大。在线安装器、Qt 账号、组件勾选、构建套件，每一个环节都可能有坑，而且很多步骤背后的逻辑如果不搞清楚，装完之后开发时还会继续踩雷。这篇文章我想完整走一遍新版本的安装配置流程，把那些容易踩到的地方和背后的原理都讲清楚，适合刚接触 Qt 的新手，也适合准备升级开发环境的老手。
1. 新版本安装逻辑的变化：在线安装器和账号体系绕不开
1.1 在线安装器的使用前提：账号与组件分发
如果你还照着几年前的文章操作，很可能在第一步就懵了：官网下载回来的不是一个大几 GB 的离线安装包，而是一个几十 MB 的在线安装器。新版本的 Qt Creator 以及 Qt 库，现在都是通过 Qt Online Installer 来安装的，开源用户也不例外。
这就带来几个直接影响：第一，你需要一个 Qt 账号，登录流程不走通，安装器根本不让你继续；第二，“离线安装包”这个词在 Qt 6 开源版本里基本消失了，商业订阅用户才有离线安装包；第三，在线安装意味着组件可以在后续随时增删，不需要为了一个模块重装整个 Qt。
很多人对强制注册账号有点抵触，但实际注册是免费的，用途也简单，选 Open Source 即可。账号体系带来的另一个好处是：你在不同电脑上都能用同一个账号管理自己的 Qt 组件列表。如果你帮同事装过环境，会发现这个机制挺适合团队标准化——大家用同一账号的话，组件列表可以对照看（当然正式协作建议各人用自己的账号）。
1.2 默认构建方向的切换：CMake 来到台前
另一个容易“看不懂新教程”的变化是：新版 Qt Creator 新建项目时，默认的构建系统是 CMake，而不是老教程里的 qmake。你新建一个项目，生成的构建文件是 CMakeLists.txt，不是 .pro。
这背后不是 Qt Creator 自己拍脑袋决定的，而是 Qt 6 时代官方推荐的构建方式整体迁移。CMake 有更成熟的生态，很多第三方库、包管理器、CI 系统都基于 CMake，Qt 自身也更方便作为子项目集成到大型工程里。qmake 还在，也被支持，但新项目向导里它的位置已经退到很后面，说明官方重心在哪。
所以配置新版 Qt Creator 时，看到 CMake、Ninja 这些词不用慌，它们是这套新构建链路上的标准配置。安装器里默认带 CMake 和 Ninja，但你也需要确认在组件勾选时没有把它们取消掉。
写到这里，我先停一下：开始配置前，最好先想清楚要装哪些东西。下一节是最容易踩坑的地方。
2. 安装前决策：版本、编译器、组件三件事
2.1 Qt 版本选择：LTS 还是尝鲜版
在组件选择列表里，你会看到从 Qt 6.2 到 Qt 6.7 甚至更新的多个版本分支，每个分支下还分不同编译器。新同学最容易纠结。
我一般给的建议是：如果不清楚怎么选，直接选当前最新的 LTS 版本（比如 6.5.x 这一批我很稳的版本）。LTS 版本维护时间长、文档齐全、社区问题沉淀多，网上搜到的解决方案基本上都能用上。想追新特性再选最新非 LTS，但不要用于生产环境，因为你可能成为踩坑第一批用户。
如果只是为了维护老项目，那就装和项目匹配的 Qt 版本，不要贸然升级。升级 Qt 版本有时候比换编译器还折腾，涉及模块接口变化、构建脚本调整、第三方库兼容性验证，完全是另一个大工程。
2.2 MinGW 与 MSVC 的取舍
在 Windows 下，每个 Qt 版本分支下面基本都有 MinGW 和 MSVC 两种库，选哪个直接决定后续整条配置链路。
| 对比项 | MinGW | MSVC |
|---|---|---|
| 安装体积 | 小，几 GB 内 | 大，还要装 VS/Build Tools |
| 调试器 | GDB | CDB（Windows SDK 提供） |
| Windows API 兼容性 | 一般 | 官方支持最完整 |
| 适合场景 | 轻量、学习、跨平台 | Windows 分发、C++ 生态混用 |
| 配置门槛 | 低 | 稍高，需要额外装 VS |
对大多数新手，学 Qt 用 MinGW 足够。但如果你打算做 Windows 桌面产品，或者要调用大量 Windows 系统库，直接用 MSVC 更合适，省得后面迁移麻烦。
特别提醒：如果安装器里勾了 Qt 6.5.3 MinGW 版本，对应的编译器版本是 MinGW 11.2.0，这个“配套版本”不能乱改。自己随便装个新版 MinGW 去配 Qt，Qt Creator 经常不识别或者编译报错。想省心就用 Qt 安装器自带的 MinGW 工具链，不要自己去官网单拉。
2.3 组件勾选：什么该装、什么可以以后补
进入具体的组件页面，以 Qt 6.5.3 为例：
- Qt 6.5.3 分支下，勾选“MinGW 11.2.0 64-bit”库（走 MinGW 路线），这就有了 Qt 本身。
- “Qt Debug Symbols”我会建议勾选，虽然体积不小，但在调试崩溃问题时能提供很多有效信息。
- “Qt Sources”建议直接勾上，排查问题时可以直接跳进 Qt 源码看实现，非常有用。很多崩溃问题看源码能一眼定位。
- 项目里需要的模块看自己情况勾，常见的有 Qt Charts、Qt Data Visualization、Qt Multimedia、Qt WebEngine 等。不确定的可以先不装，后面在安装器里补装也不麻烦。
- “Developer and Designer Tools”分支下，确认已勾选 Qt Creator、CMake、Ninja；走 MinGW 路线还要勾 MinGW 工具链（包含编译器和 GDB）。
组件里尤其容易漏的是 Qt Debug Tools 和 MinGW 工具链这两个。漏了后面就得打开安装器去补装，虽然不麻烦，但每次补装都要重新登录、扫描，挺消耗耐心。我个人的习惯是第一次就尽量勾全，省得后面惦记。
3. 安装实操记录：从下载到启动
3.1 安装器从哪里下载更快
安装器官方地址是 Qt 官网下载页，选择开源用户版本。但国内访问官网下载时，偶尔会遇到速度慢或页面加载不出来。这时候可以去清华大学开源软件镜像站找qt/archive/online_installers/目录，下载对应平台的在线安装器。
下载安装器本身很快，但安装过程中大量组件的下载还是要走官方 CDN。说实话，这个问题没有特别好的办法。我的经验是挑选网络不那么拥挤的时间段安装，比如上午或深夜，中断概率低很多。如果公司有代理网络，也可以在安装器设置里配置代理，但不建议为了安装去折腾网络环境，错峰安装是最省心的。
3.2 安装流程中的细节操作
双击安装器后：
- 输入 Qt 账号密码登录，没有就先注册，注册过程很简单，跟着流程走就行。
- 指定安装目录。这里提醒一句：不要装在带中文或空格的路径里。以前有人装到
C:\Program Files\Qt，结果后面各种构建脚本因为空格处理不当报错。我习惯用D:\Qt，干净省事。 - 进入组件选择，按上一节说的方法勾选，确认没漏掉工具链。
- 接受协议，开始安装。等待时间取决于你勾了多少内容，勾多个 Qt 版本的话十几个 GB 都很正常。
安装完成后，打开 Qt Creator，初始界面能看到默认构建好的 Kits 列表。如果列表里没有任何 Kit 或者显示无效，别慌，下一节会详细讲怎么处理。这时候其实已经进入了“安装”到“配置”的过渡阶段。
3.3 容易翻车的两个环节
翻车案例一是安装进行到一半中断。常见提示是 “Download error”。不要直接放弃，点重试一般能续上；如果反复失败，换网络环境或者错峰安装。这个阶段的心态很重要，不要因为一次中断就想重装，Qt 安装器本身是支持断点重试的。
翻车案例二是勾选组件时把编译器漏了。等创建项目时发现“没有可用套件”才回头补装。补装流程是重新打开在线安装器，登录后在“添加或移除组件”里勾选缺失项，等待安装。整个过程不复杂，但确实没必要走这一趟，所以第一次就尽量勾对。
4. 构建套件（Kit）配置：绝大多数新手卡死在这里
4.1 Kit 的本质与四个组成部分
Qt Creator 里的 Kit 不是速溶咖啡，它是一整套编译调试环境的组合配置。一个 Kit 通常包含 Qt 版本、编译器、调试器、CMake 四件事。
我习惯把它理解成“厨房配方”：Qt 版本是食材，编译器是灶具，调试器是温度计，CMake 是烹饪步骤。四样齐了，Kit 才亮绿灯；缺一样，项目就无法编译或调试。
在“工具 > 选项 > Kits”页面里：
- Qt Versions：记录各 Qt 版本的 qmake 路径。
- 编译器：记录 C、C++ 编译器的可执行路径。
- 调试器：记录 GDB 或 CDB 的路径。
- CMake：记录 CMake 可执行文件的位置。
正常情况下，安装完成后 Qt Creator 会在后台自动检测并创建对应的 Kit。你要做的只是确认 Kit 没有黄色感叹号。
4.2 自动检测失效的排查顺序
自动检测不是每次都能成功。我见过好几次“Kit 显示无编译器”或“调试器为空”的情况。排查时不要急着重装，按下面顺序来：
- 先重启 Qt Creator，有些检测结果要在启动时刷新。
- 打开“选项 > Kits > 编译器”，看有没有检测到 MinGW 或 MSVC 编译器。如果没有，点“添加 > MinGW”，手动指定 g++ 所在路径，一般在安装目录下的
Tools\mingw1130_64\bin里。 - 打开“调试器”页，看 GDB 或 CDB 是否存在。MinGW 路线对应 gdb.exe；MSVC 路线需要通过 Windows SDK 安装 CDB。
- 打开“Qt Versions”页，确认 qmake 路径指向你安装的 Qt 库，例如
D:\Qt\6.5.3\mingw_64\bin\qmake.exe。 - 回到 Kits 页面，把对应 Kit 里每个下拉框重新指定一次，点击应用，再点 OK。
这套流程能解决绝大多数无效 Kit 的问题。记住不要只修一个字段就完事，一个 Kit 里的字段是联动关系。有几个朋友问过我“为什么编译器选了 MinGW 还是不行”，最后发现是 Qt 版本那栏还指向旧版 qmake，这种联动问题排查时最容易漏。
4.3 调试器缺失导致无法调试的案例
说个具体案例。有次同事说 Qt Creator“坏了”，一按 F5 就弹“无法启动调试”或者干脆没反应。我过去一看，项目能编译，说明编译器没问题；但 Kits 里 Debugger 一栏是空的，编译器是 Detected 状态，调试器却没有检测到。
进入“调试器”页面，GDB 列表里也是空的，再检查安装时勾选的组件，发现 MinGW 工具链确实勾了，但安装器里把 GDB 单独放在一个组件里，同事当时没注意到。在安装器里补装 GDB 组件后，回到 Qt Creator 重新扫描 Kits，Debugger 自动出现，问题解决。
这个案例的启示是：编译和调试是两个独立链路的组合，编译器正常不代表调试器正常。遇到 F5 没反应，先看 Kits，而不是重装。
5. QML 开发环境的配套调整与格式化问题
5.1 QML 工程创建与调试配置
热词里不少人同时搜“Qt Creator”和“QML”，说明 QML 开发是刚需。创建一个 Qt Quick Application 项目后，首先要确认构建套件选对了，因为 QML 相关的工具链都是从 Kit 派生出来的，Kit 无效，QML 编辑器里的语法检查、补全和预览全都不会工作。
运行 QML 项目时，建议在“项目 > 运行”设置里勾选“启用 QML 调试和性能分析（仅调试构建）”。这样你在 QML 里打断点、查看对象属性变化、做性能分析时才有数据，发布版本又不会带上调试代码。
如果 QML 项目编译时报某个模块找不到，比如 Qt Quick Controls，第一反应不是版本有问题，而是回安装器里检查组件——大概率是没勾对应的模块，补装之后重新 qmake 一次就好。QML 模块的依赖关系比较隐蔽，报错信息也可能不够直白，需要留个心眼。
5.2 “代码对齐”与“格式化”不是一回事
“Qt Creator 代码对齐快捷方式不好用”这个搜索词背后，其实是一个普遍误会：大家想要的不是“对齐”，而是“格式化”。
Qt Creator 默认的自动缩进快捷键是 Ctrl+I，作用是调整当前行或选中区域的缩进层级，让代码进入正确的嵌套关系。但如果你期待的是类似int a=1自动变成int a = 1、花括号自动换行这类统一风格调整，它做不到。所以你会觉得“不好用”。
这不能怪 Qt Creator 偷懒，自动缩进和格式化是两个维度的功能。前者只处理缩进空格，后者处理空格外全部书写风格。搞清楚这一点，下一步就是配置真正的格式化工具。
5.3 用 ClangFormat 实现一键格式化的配置步骤
新版本 Qt Creator 把 ClangFormat 集成得很深，设置路径在“选项 > 格式化”。
配置步骤：
- 勾选“启用 ClangFormat”。
- 指定 clangformat 可执行文件。Qt Creator 安装目录下的
bin里通常自带一个，找不到也可以指向系统中安装的 clang-format。 - 选择样式来源。可以用内置的 LLVM、Google、Chromium 等，团队协作的话放一个
.clang-format文件到项目根目录，统一全员风格。 - 在“选项 > 环境 > 键盘”里搜索“format”，给“Format File”或“Format Selected Text”绑定你习惯的快捷键。
我自己的快捷键是 Ctrl+Alt+F，选中的代码按一下，全格式化成团队风格，比默认的自动缩进“好使”太多。设置完不用重启 Qt Creator，立刻生效。
如果发现 QML 文件没反应，检查该文件的编辑器语言模式是否识别为 QML，ClangFormat 对不同文件类型的支持是分语言配置的。这个细节很多人踩过：C++ 文件正常，QML 文件不动作，就是因为语言模式识别不到位。
6. Qt VS Tools 的安装配置与双工具协作
6.1 什么时候才真正需要 Qt VS Tools
Qt Creator 写 QML 方便，但 Windows 上不少团队仍然活在 Visual Studio 的工程体系里，比如要混用 MFC、要挂微软插件，或者公司 CI 早就写好了 .sln 构建脚本。这时候就需要 Qt VS Tools 这个桥接工具，让 VS 能直接认识、编译、调试 Qt 项目。
需要强调一点：Qt VS Tools 对应的是 MSVC 编译路线。你用 MinGW 的 Qt 路径去配它，大概率白忙一场。它要求你配置的 Qt 版本目录是 MSVC 的库目录，比如D:\Qt\6.5.3\msvc2019_64。
6.2 安装后的关键设置
在 VS 中安装扩展：从“扩展 > 管理扩展”里搜索“Qt Visual Studio Tools”，安装后重启 VS。
然后依次做三件事：
- 打开“扩展 > Qt VS Tools > Qt Versions”。
- 点击“添加”，填入 Qt 版本名称和路径。路径要选 MSVC 版本对应的目录，不要选 mingw_64。
- 新建项目时选择 Qt 模板，比如“Qt Widgets Application”，并指定刚才配好的 Qt 版本。
如果配置正确，VS 里可以直接编译运行 Qt 项目，断点时也能跳到 Qt 源码。如果提示 “Qt version is not properly installed”，99% 是路径选错了，改回 msvc 目录就行。
6.3 与 Qt Creator 的共存协作
我自己是 Qt Creator 和 VS Tools 都装的，日常写 QML 用 Qt Creator，一旦要接 Windows 原生模块或者跑团队里的 VS 工程，就切到 VS。
共存的关键是别让两套工具同时操作一个工程目录。比如一个仓库如果用 Qt Creator 打开构建过，再拿到 VS 里打开时，最好先清理或改掉构建目录名，否则两个构建系统会互相踩。反过来也一样。
这种双工具的模式在团队里很实用：不强迫每个人都学同一套 IDE，项目文件本身还是 Qt 标准的那套，只是入口不同。配置好之后，两边都能稳定干活。
最后说一点个人体会：新版本 Qt Creator 的安装配置，本质上就是搞定三组对应关系——Qt 库版本和编译器匹配、编译器体系（MinGW/MSVC）和调试器匹配、构建系统（CMake/qmake）和项目类型匹配。把这三组关系理顺了，不管界面怎么变、组件多少，都不会慌。
再补一个小技巧：如果你在同一台机器上折腾试验环境，可以把安装好的 Qt 目录整体复制到另一台机器，然后在“Qt Versions”里手动指一下路径，通常不用重新下载全部组件就能用。这个方法在团队内部分发环境时很省时间。Qt Creator 的变化节奏很快，但从实践来看，只要底层的匹配关系理清楚了，换新版本也只是多花半小时熟悉界面的事。
