★ FEATURED ARTICLE 写 Qt Quick 工程最让人窝火的不是 QML 语法报错而是新建项目那一刻Qt Creator 甩你一句Kit 缺失或者No suitable kit found。明明 Qt 装好了版本也看着没问题就是灰着下一步按钮不让你点。这篇东西我结合自己这些年折腾 Qt 开发环境的实际经历把 Kit 缺失的来龙去脉、排查顺序和手动配置方法一次讲清楚照着做基本能解决问题。1. 先搞清楚Kit 缺失到底缺了什么1.1 一个完整 Kit 由哪些零件组成很多新手把 Kit 理解成Qt 版本这是最大的误会。在 Qt Creator 里Kit构建套件是编译器、Qt 版本、调试器、CMake 或 qmake、以及针对特定设备的系统根路径这五样东西的集合体。只有这些零件全部就位且互相匹配Qt Creator 才能顺利调用它们去编译你的 Qt Quick 工程。打个比方Kit 就像一条完整的汽车生产线编译器是车间的机床Qt 版本是原材料规格CMake 或 qmake 是装配流程调试器是质检仪器。机床没接电、原材料型号不对、装配流程缺失生产线就转不起来。Qt Creator 之所以报Kit 缺失通常就是因为机床编译器或者装配流程构建工具在系统里没找到或者找到了但和原材料规格Qt 版本不匹配。具体来说一个 Kit 通常由以下部分组成编译器负责把 C 源码变成机器码。Windows 上常见的是 MinGW 的 g 或者 MSVC 的 cl.exe。Qt 版本你安装的 Qt 库的位置比如 C:\Qt\6.5.3\mingw_64这里面包含了完整的 Qt 模块和头文件。CMake 或 qmake负责生成构建规则的构建工具。Qt 6 默认用 CMakeQt 5 及以下通常用 qmake。调试器配合 IDE 做断点调试的工具Windows 上通常是 GDB 或 CDB。设备类型和系统根路径用于交叉编译到其他平台时指定目标系统的信息。任何一个零件缺失、路径指向错误、或者位数不匹配32 位编译器搭配 64 位 QtQt Creator 都会判定这个 Kit 不可用。它宁可把你拦在创建工程的门外也不会让你用一套不完整的工具链蒙混过关否则后面编译期的错误会更多。1.2 为什么 Qt Quick 工程比普通 C 工程更容易踩 Kit 坑同样一台机器创建普通 C 空项目也许能蒙混过关创建 Qt Quick 工程却经常卡在 Kit 选择上。原因在于 Qt Quick 工程对工具链的完整性要求更苛刻。Qt Quick 涉及 QML 引擎、OpenGL 图形抽象层和一系列运行时组件编译过程需要完整匹配的 Qt 模块。你在创建向导中如果选了 Qt Quick 模板Qt Creator 在校验 Kit 时会额外检查图形相关模块是否可用。某些时候一个 Kit 虽然显示黄色感叹号还允许你建普通项目但建 Qt Quick 项目时就变成红色叉号了。这也是为什么别人能建我不能建的原因之一别人的 Qt 安装勾选了完整的图形模块和对应编译器而你的安装路径里有残缺。另一个常见情况是编译器缺失。很多人图省事安装 Qt 时只选了 Qt 库本体把编译器部分漏掉了。Qt 官方安装器的图形界面上MinGW 编译器在 Tools 目录下默认是打勾的但如果你手动取消了它或者安装时没注意展开 Tools 节点装完就只有 Qt 库而没有编译器。这样 Kit 缺了最核心的编译器自然创建不了任何工程。1.3 Kit 缺失的典型表象你要先认清在动手排查之前先辨别你遇到的是哪一类表象这决定了排查方向。我总结了三类最常见的情况创建工程时Kit selection页空荡荡一个可用的 Kit 都没有系统提示 No suitable kit found。打开已有项目时自动选择的 Kit 显示红叉右下方构建按钮灰色不可点。Kit 列表里有 Kit但名称前面带黄色感叹号而且你点击它之后提示编译器和 Qt 版本不匹配。第一类表象说明 Qt Creator 在自动检测阶段什么都没找到大概率是编译器没装或者路径配置指错位置第二类表象是能检测到 Kit但某个关键组件失效比如 Qt 版本路径变了之前 D 盘的 Qt 被挪到 C 盘Qt Creator 没自动更新路径第三类表象是典型的版本不匹配问题比如拿 MinGW 32 位编译器搭配 64 位 Qt 库或者 Qt 6.5 要求 CMake 3.16 以上而系统装了更老的 CMake。看清表象之后接下来就是针对性地排查和配置。2. 创建工程前后的环境自查与组件确认2.1 安装 Qt 时的勾选清单是你少走弯路的前提我有一次为了省时间在安装 Qt 时只勾了某个版本号和 Qt Creator 本体装完傻眼了创建工程的界面干净得像张白纸。所以先说安装勾选这件事。安装 Qt 时左侧的筛选器里选择你需要的 Qt 版本比如 6.5.3但在展开它之前务必检查 Developer and Designer Tools 这一大类下的组件。以 Windows 平台为例当前主流的组合是Qt 6.x 版本本体如 Qt 6.5.3下的 MinGW 64-bit 或 MSVC 64-bit 模块。Tools 分类下的 MinGW 编译器版本号和你选的 Qt 模块一致。Tools 分类下的 CMake 和 NinjaQt 6 官方推荐。Tools 分类下的 GDB 调试器与 MinGW 配套的版本。如果你选了 MinGW 的 Qt 模块却没有勾 Tools 下的 MinGW 编译器那结果就是最常见的编译器缺失问题。微软的 MSVC 编译器则不在 Qt 安装器里需要单独安装 Visual Studio 的 C 生成工具或完整 VS。安装 VS 之后Qt Creator 一般能自动检测到 MSVC 编译器。具体勾选建议我列一下避免遗漏Qt 版本模块例如 6.5.3 下的 MinGW 64-bit这是 Qt 库的核心模块。Qt Creator必须装这是 IDE 本体。Tools 下的 MinGW编译器本体版本号必须和 Qt 模块的 MinGW 对应比如 Qt 6.5.3 要求 MinGW 11.2.0。Tools 下的 CMakeQt 6 构建系统默认使用。Tools 下的 Ninja配合 CMake 使用的新式构建工具编译速度更快。Tools 下的 GDB调试器。上面这些如果都打勾你至少有了一套官方自洽的完整工具链。这套组合下Qt Creator 在安装完成后首次启动的自动检测阶段基本能识别出可用的 Kit创建 Qt Quick 工程大概率不会卡在缺 Kit 上。2.2 编译器选型MinGW 还是 MSVCWindows 平台上选编译器是个绕不开的问题。MinGW 是 GNU 编译器套件在 Windows 上的移植版优点是不需要额外装庞大的 IDEQt 安装器自带离线也能装日常开发够用生成的可执行文件依赖较少的运行时方便拷贝出去。MSVC 是微软的编译器需要安装 Visual Studio但编译出的程序在 Windows 上的性能和兼容性通常更优某些依赖 Windows SDK 特定功能的模块只有 MSVC 版本可用。从 Kit 配置的角度看不同类型编译器对应的启动方式是两套MinGW 要直接指向 g 可执行文件MSVC 则要先在 Qt Creator 里设置 Visual Studio 的安装路径编译器路径一般不直接手动指定而是通过 VS 的安装信息自动导入。如果你想让 Qt Creator 自动检测出可用的 Kit建议在一台机器上只保留一种主用的编译器体系不要同时装 MinGW 和 MSVC否则 Kit 列表会乱自动检测也可能选错默认编译器。2.3 CMake 与 qmakeQt 6 时代的选择题Qt 6 开始官方默认转向 CMakeqmake 还在但已不做主要推荐。这意味着你创建 Qt Quick 工程时构建系统如果选 qmake部分新版模板可能直接不提供或者在 Kit 校验时要求额外的 qmake 路径配置。在 Qt Creator 中每个 Kit 需要指定 CMake 或 qmake 的位置。自动检测时Qt Creator 会找你 PATH 环境变量里的 cmake.exe 和 qmake.exe。如果你的 Qt 安装路径不在系统 PATH 里或者 CMake 是事后单独装的Qt Creator 有可能只检测到 Qt 库而检测不到构建工具。一个实用的做法是打开 Qt Creator 后进入 Options 界面的 CMake 页确认列表里有没有系统自动找到的 cmake.exe。如果列表为空点击 Add 手动指定 CMake 可执行文件路径。同样地进入 Qt Versions 页面确认 Qt 库路径是否已被识别。这些检查和 Kit 列表一样重要因为 Kit 缺构建工具时你在创建工程页面看到的同样是Kit 缺失。3. Kit 手动配置与工程创建实操3.1 从零开始的完整 Qt 6 环境搭建顺序与其在配置错误的泥潭里越陷越深不如直接从零来一套干净的环境。下面是我验证过很多次在一台新 Windows 机器上配 Qt 6 Qt Quick 开发环境的完整顺序每一步都附上选择的理由。第一步安装 Qt。用官方安装器在选择组件时勾选 Qt 6.5.3 下的 MinGW 64-bit、Tools 下的 MinGW 11.2.0、CMake、Ninja、GDB。安装目录建议直接用默认的 C:\Qt不要装在带中文或空格的路径下。某些 Qt 模块对路径中的空格敏感虽然现代版本改善了很多但没必要冒这个险。第二步安装完成后先不急着新建工程打开 Qt Creator进入 Edit 设置页面确认一下自动检测结果。路径是 Tools、Options、Kits。在 Kits 页面你会看到 Qt Creator 自动收集的各类编译器和 Qt 版本信息。正常情况下这里应该已经有一个名为Qt 6.5.3 MinGW 64-bit的 Kit编译器、Qt 版本、CMake 三行都有值。如果这个 Kit 存在且没有感叹号直接用它建工程即可。第三步如果自动检测失败或者 Kit 有条目但显示不完整点击页面底部的 Add 手动构建一个 Kit。在出现的界面里设置名称比如我的MinGW套件然后依次选择编译器 C 和 C 为 gQt 版本为 6.5.3 MinGW 64-bitCMake 为安装目录下的 cmake.exe调试器为 gdb.exe。所有项目填完保存Kit 列表里就会出现一个可用的 Kit。第四步打开环境变量检测一下路径里是否有中文字符或不存在的路径这会影响命令行的基本执行。把 C:\Qt\Tools\mingw1130_64\bin 和 C:\Qt\Tools\CMake_64\bin 加入系统 PATH重启 Qt Creator 让环境变量生效。走完上面四步Qt Creator 里应该至少有一个完全可用的 Kit 了。3.2 用配置好的 Kit 创建第一个 Qt Quick 工程现在进入实操环节从新建工程开始走一遍完整的流程。打开 Qt Creator点击 New Project在左侧选择 Application然后选 Qt Quick Application (Prototype)。这个模板比空工程多了一个最小的 QML 文件适合用来验证环境是否真正跑通了。在选择构建系统的页面Qt 6 下默认是 CMake直接保持默认。之后进入 Kit 选择页这时候你应该能看到刚才配置的 Kit 是可选状态。如果 Kit 前面有黄色感叹号鼠标悬停它系统会提示具体缺什么组件。如果提示是编译器缺失回到 Kits 页面检查编译器路径如果提示是 Qt 版本无效回到 Qt Versions 页面重新指定 qmake.exe 路径。正常情况下选好 Kit 点下一步填好工程名和存放路径然后点击 Finish。创建完成后Qt Creator 会自动进行一次 CMake 配置。你可以在界面右下角看到构建状态。之后点击左侧的运行按钮Qt Creator 会调用你选择的 Kit 编译整个工程。第一次编译需要一点时间因为 CMake 要生成构建文件、编译 C 源码、最后运行 qml 场景。看到窗口弹出来、界面正常显示一个空白的 QML 页面时说明这个工程从创建到运行已经打通了。编译过程中如果弹出无法解析外部符号或者找不到 xxx.dll之类的错误多半是 Kit 里的某个组件路径配错了。不要急着改代码优先回看 Kit 配置。3.3 三个命令行验证命令帮你定位 Kit 问题在哪个环节有些 Kit 问题 Qt Creator 的图形界面里提示得不够清楚用命令行验证反而是最快的定位手段。打开一个终端窗口依次运行三个命令看它们的输出是否符合预期。qmake --version如果系统能找到 qmake会输出类似 QMake version 3.1后面带 Qt 版本号。如果提示不是内部或外部命令说明 Qt 的 bin 目录不在环境变量 PATH 里或者装的是 Qt 6 的某些不带 qmake 的嵌入式版本。这条命令验证的是 Qt 版本本体是否可用。g --version这条验证的是编译器是否存在。输出应该是一段版本信息比如 g (MinGW.org GCC Build-2) 9.2.0。如果找不到 g说明 MinGW 编译器没装或没加入 PATH。而 Qt Creator 的自动 Kit 检测依赖这套 PATH这条命令的结果可以直接反映编译器缺失的问题。cmake --version这条验证的是 CMake 构建工具是否可用。Qt 6 构建系统离不开它。输出类似 cmake version 3.24.1 这样。如果你用的是 Qt 6.5 以上版本但 CMake 版本过低Qt Creator 会提示 CMake 版本不满足最低要求。三个命令的输出都正常至少说明工具链基本没问题。剩下的 Kit 校验 Qt Creator 会自动完成。如果任何一条命令失败按对应方向排查路径和环境变量即可。4. 高频踩坑与排查技巧实录4.1 常见 Kit 问题速查表我整理了一张速查表覆盖了实际项目里最常遇到的 Kit 相关报错和对应解法。这张表来自我多次帮同事排查问题的经验基本能覆盖 70% 以上的常见情况。现象根因解决步骤Kit 列表为空Qt 安装时未勾选编译器运行 Qt 安装器补装 Tools 下的 MinGW 或安装 Visual StudioKit 有黄色感叹号编译器路径失效或 Qt 库路径变更进入 Kits 页面重新指定编译器路径或 Qt 版本路径提示 CMake 无法找到CMake 未安装或不在 PATH安装 CMake 并加入 PATH或在 Kits 页面手动指定 cmake.exe提示 Qt 版本无效qmake.exe 路径错误在 Qt Versions 页面重新添加含 qmake.exe 的目录编译报错找不到 lg系统缺少 OpenGL 相关库安装对应图形库或在 Qt 安装器中补装 OpenGL 相关模块64 位 Qt 配 32 位编译器Qt 模板和编译器位数不一致统一为 64 位组合或重新安装对应位数的 Qt 模块打开旧项目 Kit 全红项目文件里写死的 Kit 序号已失效在项目管理页面手动重新选择可用的 KitMinGW 版本和 Qt 要求不匹配Qt 某版本要求特定 MinGW 版本对照官方文档安装要求的 MinGW 版本这张速查表的核心思路还是拆零件一个 Kit 五个零件逐个确认哪个失效就补哪个。绝大部分问题是编译器缺失和路径漂移少部分出在 Qt 版本本身位数或模块选错上。4.2 三个最容易被忽略的细节踩过的人都沉默了细节一Qt 安装目录里出现了缓存残留。有时候卸载 Qt 再重装新版本老的 qmake.exe 或 CMake 缓存还在Qt Creator 自动检测时会报告到一个旧的 Qt 版本路径导致你新建的 Kit 表面上指向新 Qt 版本实际上编译器还引用着老路径。处理办法是卸载 Qt 后把 C:\Qt 目录手工删干净或者装新版本时换一个目录名比如 C:\Qt2让 Qt Creator 彻底失去旧缓存强制重新检测。细节二环境变量 PATH 里的顺序问题。PATH 里如果同时存在 Qt 的 bin 目录和其他编译器的 bin 目录命令行和 Qt Creator 可能优先调用其中某一个。比如系统里已经有 Python 或 Ruby 自带的 GCC你再把 Qt 的 MinGW 加到 PATH两个 g 会冲突。解决办法是只让一种编译器体系出现在 PATH 中或者把 Qt 的 MinGW bin 放在 PATH 最前面确保 shim 机制先找到它。细节三Qt Creator 首次启动时没联网导致自动检测不完整。有些离线安装包或首次启动时网络受限Qt Creator 的 Kit 自动检测模块不会去扫描系统中新安装的编译器。这个问题的表现很隐蔽明明装好了Qt Creator 就是看不到。解决方法是关掉 Qt Creator 重新打开一次或者在设置页面手动触发刷新按钮。上面这三个细节我在实际中还真的都遇到过。第一个是常见的装机历史残留问题第二个是 Windows 环境变量顺序的经典坑第三个在网络隔离环境下装 Qt 很常见。每次帮人排查 Kit 问题我都会先问一句系统 PATH 怎么写的再问 Qt 安装路径有没有历史残留往往能省掉很多无谓的点击操作。4.3 如果手动配置完还是不行试试重置 Qt Creator 配置有些时候Kit 列表里的配置太混乱了手动改不如直接重置整个 IDE 的配置来得利落。Qt Creator 的设置存放在用户目录下的一个配置文件夹里Windows 上一般在 %APPDATA%\QtProject。如果你经过反复调整仍然被 Kit 问题困扰而且项目里没有极度自定义的快捷键或代码样式需要保留可以试试这个办法。操作步骤是先退出 Qt Creator备份 QtProject 文件夹然后删除整个 QtProject 目录。重启 Qt Creator 后它会像第一次安装那样运行初始化向导重新扫描编译器、Qt 版本和 CMake。只要你的工具链本身是完整的这个操作大概率能让你重新得到一个干净可用的 Kit 列表。我自己的经验是这个方法适合那些做过几百次尝试但越改越乱的场景。相比耗费大量时间一个个核对路径重置配置往往十分钟就解决问题。唯一要提醒的是重置会清掉 Qt Creator 的全局设置在下载别人分享的项目时记得先导出自己的设置或做好备份。4.4 一个我用来快速验证 Kit 是否可用的老办法创建正式的 Qt Quick 工程之前先创建一个最精简的 Qt Widgets 应用来验证 Kit。这听起来好像绕远了但这个思路真的能帮你把问题焦点缩小。步骤如下新建项目时选择 Application 下的 Qt Widgets Application。如果这个最简单的工程能用目标 Kit 编译并弹出窗口说明工具链本身没问题问题出在 Qt Quick 相关的特定模块或图形配置上。如果连 Widgets 工程也编译不了问题就出在工具链本身回到 Kits 页面做组件排查。我用这个方法多次定位到问题在 Qt Quick 模块缺失或 OpenGL 环境异常上而不是单纯的编译器问题。Widgets 工程用不到 QML 引擎和图形渲染抽象层能编译 Widgets 工程只能证明基础工具链 OK但 Qt Quick 还需要细查图形相关配置。反过来说Widgets 工程都编译不了就别浪费时间去折腾 Qt Quick 了。这个验证思路虽然不是官方文档里的标准做法但在实际交流群里帮很多人节省过排查时间。新手遇到 Kit 缺失往往在 Qt 安装器和 Kits 页面反复折腾而老手直接先建一个 Widgets 项目把问题二分定位。5. 从 Kit 缺失延伸出来的 Qt Quick 工程避坑建议5.1 工程路径和文件名中的特殊字符要避开Kit 配好了工程也创建出来了但编译期还是会冒出一堆奇奇怪怪的报错。排查到最后发现往往是工程路径里有中文字符或空格。Qt 的工具链对路径中的特殊字符友好程度参差不齐MinGW 对中文路径的支持已经比以前好很多但 MSVC 和某些 Qt 模块仍然会在包含中文或空格的路径下出问题。这属于 Kit 配置之外的工程创建规范化问题但在实际开发中确实会以 Kit 相关报错的形式出现。比如你创建的 Qt Quick 工程路径是 D:\我的项目\测试Demo在 Qt Creator 里构建时可能报Cannot open file之类的错误。建议统一用纯英文路径存放工程内部目录也不要出现空格和中文。我在公司里遇到过不止一次同事因为项目路径带了中文Qt Quick 工程编译期报一些毫无头绪的错误最后把文件夹改名为英文编译就顺利通过了。这件事说小不小说大也不大但它直接影响你能否顺利跑通第一个 Qt Quick 工程。5.2 版本号配套是长期稳定开发的保障Kit 缺失的核心根源十有八九是版本配套出了问题。Qt 版本、编译器版本、CMake 版本这三者有一套配套关系任意一环不对Kit 就不可用。Qt 6.5 搭配的 MinGW 版本是 11.2.0搭配的 CMake 最低版本是 3.16但我实际测试中 CMake 3.22 以上编译 Qt Quick 工程项目更稳定。Qt 6.2 搭配的是 MinGW 11.2.0而 Qt 5.15 搭配的是 MinGW 8.1.0。网上很多人下载了新版 Qt却沿用旧版开源社区的 MinGW结果 Kit 一直报版本不匹配。具体核对方法很简单打开 Qt 安装器在已安装的组件列表里看 Qt 版本号旁边的工具链说明。或者打开 Qt 官方发布说明页面里面明确写了每个版本对应的工具链版本要求。我在配置环境时都是先选定 Qt 大版本再选官方推荐对应的 MinGW 版本最后装配套的 CMake 和 Ninja。这套组合所有版本号都是官方验证过的Kit 基本不会出问题。5.3 长期角度使用 CMake 预设文件规范 Kit 选择项目规模上来以后团队多人开发时 Kit 混乱的问题会放大。每个人本地的 Qt 路径不同、编译器版本不同提交到代码库的 CMake 文件不同会导致别人打开工程时 Kit 全部红叉。这时候可以引入 CMake 预设文件来规范构建配置。具体做法是在工程根目录下添加 CMakePresets.json 文件里面定义不同平台下的配置预设包括编译器路径、CMake 选项和生成器类型。Qt Creator 新版本会读取这个文件自动配对预设和本地环境。这样团队协作时每个人打开工程后 Qt Creator 能根据预设自动找到合适的工具链Kit 缺少的问题会大幅缓解。文件的大致格式可以这样写{ version: 3, configurePresets: [ { name: windows-base, displayName: Windows Base, generator: Ninja, binaryDir: ${sourceDir}/build/${presetName}, cacheVariables: { CMAKE_C_COMPILER: gcc, CMAKE_CXX_COMPILER: g } } ] }我这里只写了骨架实际使用时要根据你本地的编译器路径填对应的值。CMake 预设的好处是把构建参数和 IDE 界面解耦Qt Creator 能自动读取并匹配 Kit省去手动选择步骤。环境越复杂越值得用。6. 我踩过 Kit 缺失坑之后的三点心得体会第一点体会Kit 缺失不是玄学是配置管理问题。它和编码能力无关纯粹是工具链装配这件事没做好。把 Kit 拆成编译器、Qt 版本、CMake、调试器四个零件逐个验证问题一定能定位。我见过太多人在群里咨询这个报错其实自己电脑里有完整工具链只是 Qt Creator 没告诉他路径而已。第二点体会官方安装器的默认勾选能不动就别动。很多人安装 Qt 时看到 Tools 下的 MinGW 编译器目录被展开误以为那是多余的主动取消打勾。结果就是缺编译器。官方把那些工具和 Qt 库放在一起是有原因的它们就是用来组成 Kit 的标准零件。减少自己对默认勾选的主观改动Kit 问题自动少一半。第三点体会环境的干净程度决定了你的开发效率。一个历史残留多、PATH 混乱、多个编译器版本并存的系统即使你这次解决了 Kit 缺失下次还会遇到构建系统冲突的问题。不如痛下决心重装一次干净的 Qt 环境把工具链理顺一劳永逸。判断你的环境是否干净一个简单标准是当你运行 qmake --version、g --version、cmake --version 三条命令时输出都应指向你的 Qt 安装目录下对应的可执行文件而不是系统某个犄角旮旯里的旧版本。如果输出里有任何一条指向了想不到的位置就说明环境不干净迟早会出问题。
阅读完成 · 觉得有帮助？
