★ FEATURED ARTICLE 装 Qt 这件事很多人第一次都是在安装器进度条走到 100% 之后才真正开始踩坑的。安装包下完、组件勾完、Qt Creator 也启动了结果新建工程一编译底下红字一片不是提示找不到 Qt 版本就是 Kits 里那一栏灰着点不动。我在几台不同配置的机器上重复过这套流程从 Windows 64 位安装 Qt 6.8.0 到把 Kits 配置彻底跑通前后踩过的坑能凑出一份小手册。这篇就按我自己的实际操作顺序把下载、组件勾选、工具链搭配、Kits 绑定、第一个工程验证这几段拆开讲每一段都说明白为什么要这么选以及选错了会以什么形式报错。适合刚接触 Qt 6 系列、准备在 Windows 上搭一套长期可用环境的人看也适合已经装完但 Kits 一直配不顺、想搞清楚背后逻辑的人对照排查。1. 装 Qt 卡住新人的从来不是下一步按钮1.1 三个最典型的失败现场我见过最多的第一种情况安装器全程默认下一步组件只勾了最上面那个 Qt 6.8.0 大项装完打开 Qt Creator新建一个 Widgets 应用构建按钮是灰的。打开工具 - 选项 - 构建和运行Kits 列表里躺着一个带感叹号的条目鼠标悬停提示未设置 Qt 版本。这不是软件坏了而是安装时根本没装任何一套编译套件只装了一个空的版本目录。第二种情况是 Kits 看起来全绿编译也能过但一按调试就卡住弹窗说调试器没配置。这套环境通常是选了 MSVC 编译器Visual Studio 装了可 Windows SDK 里的调试工具那一项没勾CDB 压根不在机器上。Qt Creator 能调起编译器生成 exe但它不会自己去给你补一个调试器。第三种更隐蔽编译报错说找不到某个 Qt 模块的 CMake 配置文件路径里明明白白写着 Qt6Config.cmake 的位置可那个目录确实存在。这种情况八成是 Kits 里绑定的 Qt 版本指向了另一个没有安装该模块的目录或者干脆是手动改过 CMAKE_PREFIX_PATH 之后留下的陈旧缓存。1.2 安装器为什么不给你一步到位Qt 的在线安装器本质上不是一个安装软件的工具而是一个组件包管理器。它把 Qt 库、编译器套件、Qt Creator、源码、文档、示例全部拆成独立条目让你自己组合。这么设计的理由很实际Qt 支持的平台和工具链组合太多一个 Windows 用户可能用 MSVC也可能用 MinGW还可能两个都要用来做交叉验证有人需要源码调试有人只要二进制。全塞进一个包里安装体积会翻好几倍。代价就是第一次接触的人必须自己完成选型这件事。而 Qt Creator 的 Kits 机制又恰好要求这些组件之间严格对应一个 Kit 等于一个编译器加一个调试器加一个 Qt 版本加一套构建工具四个要素必须互相匹配。缺一个Kit 就是不可用的配错一个编译能过但运行或调试会出问题。记住这个等式可用的 Kit 编译器 调试器 Qt 版本 构建工具CMake/Ninja 或 qmake/make。后面所有章节其实都在围绕这一个等式展开。2. 先定路线这套环境到底用 MSVC 还是 MinGW2.1 两条工具链在 Windows 上的真实差别这个问题在论坛里被问了无数遍答案从来不是哪个更好而是你要拿它做什么。我把两者在实际使用中的差异整理成了一张表都是我自己反复切换后记下来的体感对比项MSVC 2022 64-bitMinGW 13.1.0 64-bit安装前提需另装 Visual Studio 或 Build Tools安装器自带勾上就有调试器CDB需 Windows SDK 调试工具GDB随组件自带编译速度中等偏快大型工程增量编译表现好稍慢但小工程感知不明显与第三方库兼容商业库、系统 API 支持最完整部分预编译库只提供 MSVC 版本生成物依赖需 VC 运行库需 libgcc、libstdc 等动态库上手难度前置步骤多勾完即用最省心MinGW 最大的优势是自包含。安装器勾上 MinGW 13.1.0 那一项编译器、GDB 调试器、配套的 make 全部到位装完就能编译不需要再去装几百兆的开发工具。对刚开始学 Qt、只想先把窗口跑出来的人这条路阻力最小。MSVC 的优势在于生态。Windows 平台上大量第三方库的预编译二进制是按 MSVC 构建的你拿 MinGW 去链接会遇到 ABI 不兼容只能自己从源码编。另外如果工程最终要接入系统级 API 或某些商业组件MSVC 几乎是唯一选择。2.2 我的选择建议如果这台机器主要用来学习 Qt 框架本身、写写小工具、做课程作业直接上 MinGW别犹豫。省下来的时间足够你多写几个 Demo。如果目标是把 Qt 用在正式项目上或者需要对接已有的 C 代码库选 MSVC并且提前把 Visual Studio 的 C 桌面开发工作负载装好。这一步建议放在装 Qt 之前做因为安装器在检测到已有 VS 时会自动识别编译器路径Kits 的自动配置成功率会高很多。还有个经常被忽略的选项两个都装。磁盘上多占几个 G但换来的是遇到兼容性问题时能快速切换验证。我自己的主力机器就是两套并存什么时候某个库在 MinGW 下链接失败切到 MSVC 的 Kit 上几秒钟就能确认是不是工具链的问题。提示同一台机器装两套工具链时务必让它们的 Kit 名称有明确区分比如在 Kit 名字里带上工具链后缀。默认命名在多套环境下极容易点错编译出一个用错运行库的 exe排查起来非常费劲。3. 下载环节安装器版本与账号这两道小门槛3.1 在线安装器的工作机制Qt 6 之后官方只提供在线安装器文件名形如 qt-online-installer-windows-x64-4.x.x.exe前面的 4.x 是安装器自身的版本号和你要装的 Qt 版本没关系。安装器启动后会先连服务器拉取一份组件清单你看到的那些勾选项就是清单渲染出来的结果。这意味着两件事第一安装过程中必须保持网络畅通中途断线会停在某个组件上下不来第二组件清单会随时间变化不同时期下载同一个安装器看到的可选项目可能不一样。安装器需要登录一个账号才能继续。这一步让不少人卡住其实注册流程很直接用邮箱走一遍就行不需要任何额外验证。登录的意义在于记录你下载过哪些组件方便后续用同一个安装器做增量维护。安装器本体建议放在一个固定的、路径里不含中文和空格的目录下。我自己的习惯是专门建一个 tools 目录把安装器和后续所有开发工具都放进去。路径带空格在 Windows 上大部分时候没事但一旦涉及到某些老旧的构建脚本或者第三方工具调用空格会被当成参数分隔符报出来的错往往和实际情况八竿子打不着。3.2 安装目录的规划到了选安装路径那一步安装器默认会往用户目录下塞路径里通常带用户名。这个默认值能改就改理由有三个。第一是路径长度。Windows 对路径总长度有 260 字符的传统限制虽然现在可以开启长路径支持但很多工具链组件并没有完全适配。Qt 的目录结构本身就不浅比如 Qt/6.8.0/msvc2022_64/lib/cmake/Qt6Core再叠加工程路径很容易触到边界。安装在 C:\Qt 这种短路径下能省掉大量莫名其妙的文件找不到。第二是权限。装在用户目录下看似不需要管理员权限但某些组件会往系统位置写东西权限混用反而更容易出问题。装在一个独立的顶层目录权限模型更清晰。第三是多用户和多版本。C:\Qt 这种位置后续装 6.9、6.10 或者换一台机器复用配置时路径结构保持一致迁移成本最低。我的实际目录结构长这样C:\Qt\ ├── 6.8.0\ │ ├── msvc2022_64\ │ └── mingw_64\ ├── Tools\ │ ├── CMake\ │ ├── Ninja\ │ └── mingw1310_64\ └── MaintenanceTool.exe这个结构是安装器自动生成的只要你在安装路径那一步填 C:\Qt后面所有组件都会按这个层级落位。MaintenanceTool.exe 是维护入口后面增删组件、卸载都靠它位置记牢。4. 组件勾选这一步决定了后面一半的坑4.1 必选清单与理由组件树展开后条目非常多但真正需要动脑的只有几层。以 Qt 6.8.0 为例我按必选、按需、可不选三档给个清单组件归属建议说明Qt 6.8.0 下的 msvc2022_64 或 mingw_64Qt 库必选至少选一个这是核心库Qt CreatorTools必选官方 IDE集成 Kits 管理MinGW 13.1.0 64-bitTools选 MinGW 路线时必选提供编译器与 GDBCMakeTools必选Qt 6 默认构建系统NinjaTools必选CMake 的高效生成器后端Qt Debug Information FilesQt 库建议崩溃调用栈需要符号才能看懂SourcesQt 库建议想看框架实现时离不开Qt Quick 3D、Qt Charts 等附加模块子模块按需不确定就先不装能后补Android、WebAssembly 相关平台一般不选体积大Windows 开发用不上这里要重点说一下 CMake 和 Ninja。Qt 6 全面转向 CMake 构建qmake 虽然还在但已不是主推。安装器里的 CMake 是独立版本和 Qt Creator 内置的那份不是一回事。如果你不装Qt Creator 会尝试用系统里的 CMake没装的话 Kit 的构建配置那一栏就是空的点构建直接报错。Ninja 同理它是 CMake 实际调用去执行编译的工具不装的话 CMake 会退回到用 NMake速度慢一截而且在并行编译时更容易出问题。Qt Debug Information Files 这个组件很多人跳过理由是我不调试。但只要程序崩溃过一次、看到过那种只有地址没有函数名的调用栈就会明白它的价值。这些符号文件能让崩溃堆栈显示到具体的函数和行号排查效率差别巨大。4.2 那些看起来有用其实可以先放着的Qt 6.8 的组件列表里有一大堆附加模块Qt Charts、Qt Data Visualization、Qt Network Authorization、Qt Virtual Keyboard、Qt Quick 3D 等等。新人常见的心态是全勾上以防万一结果装了两三个小时磁盘里躺着一堆永远不会 include 的库。我的做法是第一次安装只勾核心库加 Qt Creator、CMake、Ninja、调试符号、源码附加模块一个不碰。等实际工程里真的需要某个模块打开 MaintenanceTool 增补就行它支持增量安装不用重装整套。这样第一次安装能压缩到二十分钟上下也避免了组件多了之后 Kit 配置界面里出现多个版本条目造成混淆。注意Android 那一整组组件体积非常大动辄几个 G而且需要额外配置 JDK、SDK、NDK 才能用。不在 Windows 上做移动端开发的话这一整组都不要勾。勾完组件点下一步会显示一个许可协议列表逐项接受后开始下载。这一步的进度和网络状况强相关卡在某个组件不动的时候不要急着关掉先等几分钟确实没动静再考虑换时间重试。5. Kits 配置把编译器、调试器、CMake 串成一个闭环5.1 Qt 版本的登记安装完成后第一次启动 Qt Creator它会自动扫描安装目录把检测到的 Qt 版本填进工具 - 选项 - 构建和运行 - Qt 版本里。正常的条目应该显示版本号、平台、以及一个指向 qmake.exe 的完整路径前面打绿勾。如果这里空空如也或者条目带红叉先手动点添加浏览到类似 C:\Qt\6.8.0\mingw_64\bin\qmake.exe 的位置自己指定。这里有个容易搞错的点qmake 的路径在 Qt 6 里主要是给版本识别用的实际构建走 CMake但 Qt Creator 依然靠 qmake.exe 的存在来定位整个安装前缀所以这个文件必须存在。再检查一下版本条目下面的详情正常情况下会列出 CMake 前缀路径、库路径、头文件路径。如果这几项是空的说明目录结构不完整可能是安装被中断过用 MaintenanceTool 做一次修复。5.2 编译器与调试器的配对逻辑切到构建套件Kit标签页这里才是真正的战场。一个 Kit 里需要关注的字段有五个编译器 C、编译器 C、调试器、CMake 工具、Qt 版本。MinGW 路线的配置相对简单。编译器那一栏C 选 gcc.exeC 选 g.exe路径都在 C:\Qt\Tools\mingw1310_64\bin 下面。调试器选 gdb.exe路径同一目录。CMake 工具选安装器装的那份Ninja 会自动被识别。Qt 版本选刚才确认过的 mingw_64 条目。五个字段填完Kit 前面的感叹号应该消失。MSVC 路线麻烦一点。编译器要选到 Visual Studio 安装目录下的 cl.exe通常 Qt Creator 会自动检测并列出候选名字类似Microsoft Visual C Compiler 17.x (amd64)。调试器这一栏如果显示无说明 CDB 没装。解决办法是打开 Visual Studio Installer修改现有安装在单个组件里勾选Windows 的调试工具装完重启 Qt Creator 就能识别。这里有个特别容易踩的坑MSVC 的 Kit 里如果调试器一栏是空的编译运行是可以的点击运行按钮程序正常启动但一旦下断点调试就会失败。很多人因此误以为是代码问题其实只是缺了 CDB。所以配完 Kit 后第一件事应该是用调试模式跑一次而不是直接用运行模式。5.3 CMake 工具这一栏为什么必须手动确认Qt Creator 的 CMake 配置里CMake 工具指向的是一个可执行文件它决定了构建时用哪个版本的 CMake 来生成工程。这个路径默认可能指向系统 PATH 里的某个 CMake如果机器上装过其他版本的 CMake就会出现版本不匹配。Qt 6.8 对 CMake 的最低版本要求是 3.16但实际组件里用到的特性建议至少 3.21 以上。安装器自带的 CMake 通常是 3.29 左右直接用就行。检查方法是切到工具 - 选项 - CMake - 工具看列表里有没有那条指向 C:\Qt\Tools\CMake\bin\cmake.exe 的条目并且自动检测列打勾。如果列表里有多个 CMake建议把非 Qt 安装目录的那几条手动禁用避免 Kit 里选错。CMake 版本差异带来的报错通常长这样CMake Error: Could not find a package configuration file provided by Qt6但路径明明是对的。这种情况十有八九不是 Qt 装坏了而是 CMake 用了一个奇怪的搜索根目录。6. 第一个工程验证与报错对照6.1 从新建到窗口弹出环境配好之后最好用一个全新的空工程做验证而不是打开已有的老项目避免把历史配置问题混进来。新建工程选Application (Qt) - Qt Widgets Application构建系统选 CMakeKit 选刚配好的那个。向导里会生成 CMakeLists.txt、main.cpp、mainwindow.cpp 这些文件。点构建正常情况下底部编译输出会刷出一串 CMake 配置信息和编译命令最后显示构建成功。第一次构建会比较慢因为 CMake 需要配置整个工程、生成构建文件Ninja 再执行编译。后续增量构建就快了。构建完成后点运行应该弹出一个空白窗口。这一步如果没过先别急着搜报错信息按下面的顺序自查Kit 是否选中、CMake 工具路径是否有效、Qt 版本是否是绿的、编译器是否能单独跑通。这四项任何一个有问题报错信息都会指向完全不同的方向。6.2 常见报错与对应根因报错信息关键词大概率根因处理方式Kit has no Qt versionQt 版本未登记或 Kit 未绑定在 Kit 页签手动指定 Qt 版本Could not find CMAKE_CXX_COMPILER编译器路径失效重新指定编译器确认 bin 目录存在Could not find a package configuration file provided by Qt6CMake 前缀路径不对或 Qt 版本选错检查 Kit 绑定的 Qt 版本目录下 lib/cmake/Qt6 是否存在No CMake configuration foundCMake 工具未指定在 CMake 工具页签选定有效路径error: cannot find -lQt6Widgets库路径缺失多见于手动改过构建目录删除构建目录重新配置构建成功但运行闪退缺少运行库 DLL检查 PATH 或改用 windeployqt 部署构建目录这一项值得单独说。Qt Creator 默认会把构建产物放在工程目录同级的 build-xxx 目录里如果中途换过 Kit 或者改过 CMake 参数旧的构建目录里会残留 CMakeCache.txt记录着上一次的配置。这个缓存不会自动清理新的配置和旧的缓存打架报出来的错经常是找不到某个库但库明明就在那里。遇到解释不通的构建失败第一反应应该是删掉整个构建目录重来这一招解决过我遇到的大部分玄学问题。7. 多版本共存与后续维护的正确姿势7.1 用维护工具而不是重装Qt 的版本迭代比较频繁一年里可能装好几个小版本。正确做法是始终用安装目录下的 MaintenanceTool.exe 来增删组件不要手动删目录也不要为了装新版本重新下载安装器。打开 MaintenanceTool 后有两个选项添加或移除组件和更新组件。前者用来增补新的 Qt 版本或者补装漏掉的模块后者用来把现有组件升到小版本。选添加或移除时会重新拉取组件清单你可以在里面勾选新增的 Qt 6.9.0 目录它会和现有的 6.8.0 并存互不干扰。新版本装好后Qt Creator 里会多出对应的 Qt 版本条目但 Kit 不会自动创建。需要手动复制一份现有 Kit改个名字把 Qt 版本字段换成新的编译器等其他字段保持不动。这样两套 Kit 可以并存工程里随时切换做兼容性验证。7.2 环境变量这件事尽量少碰很多人喜欢把 Qt 的 bin 目录加进系统 PATH图的是命令行里能直接调用 windeployqt。这个做法在单版本机器上问题不大但一旦装了多个版本PATH 里只能有一个优先项命令行调用时会用错版本而且这种错误非常隐蔽因为工具本身不会报错只是行为不符合预期。我的做法是不动系统 PATH需要用到某个工具时在 Qt Creator 的环境配置里针对单个 Kit 追加路径或者干脆开一个临时的命令行窗口先 set PATH 再执行。工程层面则依赖 CMake 的 find_package 和 Qt Creator 传进来的变量不需要全局环境变量参与。如果确实要在发布时部署依赖用 windeployqt 最稳妥。完整路径调用明确指定 exe 文件和目标目录C:\Qt\6.8.0\mingw_64\bin\windeployqt.exe --release --no-translations D:\build\app.exe这个命令会把运行所需的 DLL、平台插件、必要的资源文件拷到 exe 同目录。参数里的 --no-translations 是砍掉翻译文件体积能小一截如果你的程序不需要多语言界面加上这个很划算。7.3 卸载时的清理顺序真要彻底卸掉某套环境顺序是先跑 MaintenanceTool 移除 Qt 组件再用系统设置卸载 Visual Studio 或 MinGW 工具链最后手动清理残留目录。反过来的话MaintenanceTool 可能因为找不到依赖而报错退出。卸载完之后配置文件目录也需要看一眼。Qt Creator 的用户配置一般放在用户目录下的 AppData\Roaming\QtProject 里里面存着 Kit 定义、会话记录、快捷键配置。如果重装后 Kits 列表里出现了幽灵条目指向已经不存在的路径多半是这个目录里的旧配置没清。这一整套流程走下来从下载到第一个窗口弹出来顺利的话一个小时内能完成。真正耗时间的从来不是点击操作而是遇到报错时不知道该往哪个方向查。把上面那个可用的 Kit 编译器 调试器 Qt 版本 构建工具的等式记住任何构建失败都先按这四项逐一确认排查范围立刻就能缩小到很小的一块。我自己后来再装新机器基本就是照着这个顺序走一遍中间不再需要试错。
阅读完成 · 觉得有帮助？
