上个星期帮团队里新来的同学配置 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 系统都基于 CMakeQt 自身也更方便作为子项目集成到大型工程里。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 两种库选哪个直接决定后续整条配置链路。对比项MinGWMSVC安装体积小几 GB 内大还要装 VS/Build Tools调试器GDBCDBWindows SDK 提供Windows API 兼容性一般官方支持最完整适合场景轻量、学习、跨平台Windows 分发、C 生态混用配置门槛低稍高需要额外装 VS对大多数新手学 Qt 用 MinGW 足够。但如果你打算做 Windows 桌面产品或者要调用大量 Windows 系统库直接用 MSVC 更合适省得后面迁移麻烦。特别提醒如果安装器里勾了 Qt 6.5.3 MinGW 版本对应的编译器版本是 MinGW 11.2.0这个“配套版本”不能乱改。自己随便装个新版 MinGW 去配 QtQt 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.exeMSVC 路线需要通过 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 重新扫描 KitsDebugger 自动出现问题解决。这个案例的启示是编译和调试是两个独立链路的组合编译器正常不代表调试器正常。遇到 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 默认的自动缩进快捷键是 CtrlI作用是调整当前行或选中区域的缩进层级让代码进入正确的嵌套关系。但如果你期待的是类似int a1自动变成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”绑定你习惯的快捷键。我自己的快捷键是 CtrlAltF选中的代码按一下全格式化成团队风格比默认的自动缩进“好使”太多。设置完不用重启 Qt Creator立刻生效。如果发现 QML 文件没反应检查该文件的编辑器语言模式是否识别为 QMLClangFormat 对不同文件类型的支持是分语言配置的。这个细节很多人踩过C 文件正常QML 文件不动作就是因为语言模式识别不到位。6. Qt VS Tools 的安装配置与双工具协作6.1 什么时候才真正需要 Qt VS ToolsQt 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 的变化节奏很快但从实践来看只要底层的匹配关系理清楚了换新版本也只是多花半小时熟悉界面的事。
