Qt Creator安装需手动勾选编译器、Qt版本及工具链组件，正确配置Kit（编译器+Qt版本+调试器），确保勾选Qt Widgets等必要模块，项目路径须为纯英文，windeployqt依赖环境纯净。

Qt Creator 安装时选错组件会导致 qmake 找不到或 mingw/msvc 工具链不完整

安装 Qt 时不能只点「Next」一路到底。默认勾选的组件往往只含基础模块，缺少编译器支持和调试工具。Qt Creator 本身是 IDE，但真正编译项目靠的是外部工具链（如 MinGW 或 MSVC），而这些必须在 Qt Online Installer 中显式勾选。

实操建议：

Linux Distros

Linux发行版游乐场，适用于需要临时Linux沙箱、基于浏览器的Linux虚拟机、一次性终端环境、桌面Linux会话等场景

下载

• 下载官方 Qt Online Installer（不是离线版，它更新及时且组件可选）
• 安装过程中展开 Qt 版本节点，务必勾选对应平台的预编译套件，例如：Desktop gcc 64-bit（Linux/macOS）、MinGW 11.2 64-bit（Windows）、MSVC2019 64-bit（需先装 Visual Studio）
• 同时勾选 Qt Creator（最新稳定版即可，不必用预览版）和 Developer and Designer Tools（含 Qt Designer、qmake、windeployqt 等）
• 安装路径避免中文、空格、长路径（如 C:\Qt 最稳妥）

启动 Qt Creator 后提示 “No valid kits found” 是 Kit 配置没对上

Kit 是 Qt Creator 里把编译器、Qt 版本、调试器三者绑定的抽象配置。即使装了 MinGW 和 Qt，若 Kit 未识别或手动配错，新建项目会直接失败。

常见错误现象：

立即学习“C++免费学习笔记（深入）”；

• Kit 列表为空，或显示 Unconfigured
• 选择 Kit 后构建按钮灰色，或报错 Could not determine which CMake generator to use（误用了 CMake 模板却没配 CMake 工具）
• 运行时提示 The program has unexpectedly finished，其实是调试器没连上

实操建议：

• 进 Tools → Options → Kits，检查 Compilers 标签页是否识别出已安装的 g++（MinGW）或 cl.exe（MSVC）；没识别就手动添加路径，如 C:\Qt\Tools\mingw112_64\bin\g++.exe
• 在 Qt Versions 标签页确认 qmake 路径正确，比如 C:\Qt\6.5.3\mingw_64\bin\qmake.exe；若为空，点击「Add」并定位到对应 bin 目录下的 qmake.exe
• 回到 Kits 标签页，新建或编辑一个 Kit：名称自定，Compiler 选刚配好的，Qt version 选刚加的，Debugger 若 Windows 下用 MinGW 就选 gdb（路径一般在同级 mingw112_64\bin\gdb.exe）

新建项目后 qmake 报错 “Project ERROR: Unknown module(s) in QT: widgets”

这是 .pro 文件里写了 QT += widgets，但当前 Qt 版本没编译 widgets 模块——常见于安装时漏选 Qt Widgets 组件，或误用了 Qt for WebAssembly 等精简版。

使用场景：

• 用 QMainWindow、QPushButton 等传统桌面控件时必须有 widgets 模块
• Qt 6 默认拆分模块，core 和 gui 是基础，widgets 是独立可选模块

实操建议：

• 检查安装时是否勾选了 Qt Widgets（在 Qt 版本节点下，和 Core、Gui 并列）；没勾选就重装或用 MaintenanceTool 补装
• 确认 .pro 文件中 QT += core gui widgets 写全，Qt 6 不再默认包含 widgets
• 如果用的是 Qt 6.5+ 的 cmake 项目模板，别混用 qmake 语法；此时应删掉 .pro，改用 CMakeLists.txt 声明 find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets)

中文路径或环境变量冲突会让 windeployqt 失效或生成空白 release 目录

windeployqt 是发布 Windows 应用的关键工具，但它极度依赖路径干净、编码一致、权限正常。一旦项目路径含中文、空格，或系统 PATH 里混入旧版 Qt 工具，就可能静默失败。

性能与兼容性影响：

• 路径含中文 → windeployqt 解析 .dll 依赖时报 Invalid argument，不报错但不拷贝任何文件
• PATH 中存在多个 qmake 或 windeployqt → 实际调用版本错乱，Qt 6 项目用 Qt 5 的 windeployqt 会漏拷 Qt6Widgets.dll
• 以普通用户权限运行 Qt Creator → 无法写入 Program Files 类路径，导致部署中断

实操建议：

• 项目根目录用纯英文短路径，如 D:\dev\myapp，避开 OneDrive、桌面等同步目录
• 构建前，在 Qt Creator 的 Projects → Build Settings → Build Environment 中点击「Details」→「Clean»，再手动删掉所有 Qt 相关条目，仅保留系统必要 PATH
• 发布时右键项目 → Deploy Project，或命令行进入 build-xxx-Desktop_Qt_6_5_3_MinGW_64_bit-Release\release 目录，运行：
  ..\..\Qt\6.5.3\mingw_64\bin\windeployqt.exe --no-translations --no-opengl-sw myapp.exe

Qt 开发环境最麻烦的从来不是装多少东西，而是每个环节都得对齐：安装组件、Kit 配置、模块引用、路径规范，缺一不可。尤其是 windeployqt 这类后期工具，问题常在发布阶段才暴露，但根子早在创建第一个 Kit 时就埋下了。