简介本资源是一个面向Qt初学者与跨平台开发入门者的轻量级安装与项目配置Demo聚焦解决环境搭建后首个GUI工程创建与编译运行的实操困惑。压缩包共6个文件5KB包含2个核心源码文件mainwindow.cpp、main.cpp、1个头文件mainwindow.h、1个UI界面定义mainwindow.ui、1个Qt项目配置文件untitled.pro及1个用户配置文件.pro.user完整呈现了标准Qt Widgets应用的最小可运行结构便于对照理解项目组织逻辑与构建流程。已有556人学习下载适合刚完成Qt安装、亟需验证环境并建立首个工程认知的学习者。读者可直接解压导入Qt Creator快速观察UI设计、信号槽连接、主窗口初始化等关键环节的实际代码组织方式同时为后续自定义插件集成或模块化开发提供清晰的起点参考。1. Qt 软件安装 demo 示例不是点下一步就完事而是让新手第一次编译就跑出窗口、不卡在“找不到 qmake”或“CMake Error at CMakeLists.txt”上你刚下载完 Qt Online Installer双击运行勾选了 Desktop MinGW、Qt Creator、C 工具链点完“下一步”以为万事大吉——结果打开 Qt Creator新建一个 Widget Application点击绿色三角形运行弹出报错“Kit is not valid: No compiler defined” 或更玄学的 “qmake not found in PATH”甚至 CMake 报 “Could not find a package configuration file for ‘Qt6’”。这不是你手残是 Qt 安装流程里埋了三道隐形关卡环境变量未生效、Kit 配置未绑定、项目模板默认启用了高版本 Qt 但你只装了低版本。这个“Qt 软件安装 demo 示例”要解决的就是把这三道关卡拆成可验证、可回溯、可截图复现的最小闭环从安装包落地到第一个可交互窗口弹出全程不依赖网络、不修改注册表、不碰系统级 PATH所有操作都在 Qt Creator 内完成且每一步失败都能立刻定位到具体配置项。适合刚接触桌面开发的嵌入式转岗工程师、高校课程设计学生、以及被跨平台 GUI 卡在起跑线超过 2 小时的 Python 后端开发者。2. 用 Qt Online Installer 完成最小可信安装只勾这 4 项跳过所有“推荐组件”Qt 安装不是越全越好。官方安装器默认勾选 WebEngine、Quick3D、Android/iOS 工具链等——这些不仅拖慢安装单 WebEngine 就 2GB还会污染 Kit 列表、干扰编译器识别。我们只保留最精简、最稳定、最易验证的组合确保首次编译 100% 成功。2.1 下载与静默校验安装包完整性Qt 官方提供两种安装方式Online Installer在线和 Offline Installer离线。强烈建议新手用 Offline Installer原因有三避免安装中途断网导致 Qt Creator 半残曾有某高校实验室因校园网策略拦截 Qt 更新服务器安装卡在 98% 两小时离线包自带校验哈希可提前确认下载无损Online Installer 无此机制安装过程不联网杜绝后台静默下载未知组件。前往 Qt 官方下载页关键词搜索 “qt-unified-windows-x64-offline”下载对应你系统架构的离线包如Qt_Untified_Windows_x64_offline.exe。下载完成后用 PowerShell 执行校验以 v6.7.2 为例# 进入下载目录执行 Get-FileHash .\Qt_Untified_Windows_x64_offline.exe -Algorithm SHA256 | Format-List比对官网发布的 SHA256 值通常在下载页下方小字注明必须完全一致才继续。曾有镜像站分发包被篡改导致安装后 qmake 生成的 Makefile 缺失-stdc17标志编译直接报auto类型推导错误——这种坑校验能 100% 规避。2.2 安装时只勾选这 4 个组件含路径硬约束运行离线安装器登录/跳过账号步骤后进入组件选择页。严格按以下勾选其余全部取消组件路径是否勾选强制理由Qt Qt 6.7.2 MinGW 11.2 64-bit✅ 必选提供qmake、moc、uic及完整 MinGW 工具链是 Windows 下最轻量稳定的组合Developer and Designer Tools Qt Creator 12.0.2✅ 必选IDE 本体注意版本号需 ≥12.0旧版对 Qt6 支持不全Additional Libraries Qt 6.7.2 Qt Charts❌ 不选非核心首次安装引入额外依赖风险Additional Libraries Qt 6.7.2 Qt SVG❌ 不选同上且 SVG 模块在 MinGW 下需额外编译 freetype新手极易翻车提示安装路径必须为纯英文、无空格、无中文错误路径示例C:\Program Files\Qt空格触发 qmake 解析失败、D:\开发工具\Qt中文路径导致 moc 生成头文件乱码正确路径示例C:\Qt\672或D:\Qt672—— 我个人习惯用D:\Qt672因为后续所有教程命令都基于此路径避免你还要替换路径字符串。安装完成后不要立即启动 Qt Creator。先验证基础工具链是否就位# 打开 CMD非 PowerShellcd 到你的安装路径 cd D:\Qt672\6.7.2\mingw_64\bin dir qmake.exe moc.exe uic.exe应看到三个.exe文件。若报 “系统找不到指定的路径”说明安装路径填错若dir无输出说明组件未勾选成功需重装。3. 在 Qt Creator 中手动配置 Kit绕过自动检测失效直连编译器与 Qt 版本Qt Creator 启动后默认会尝试自动扫描系统中的编译器和 Qt 版本。但在 Windows 上这个自动检测有三大失效场景MinGW 安装路径含空格如C:\Program Files\...导致路径解析截断多版本 Qt 共存时自动匹配错误版本如你装了 Qt5 和 Qt6它默认绑 Qt5杀毒软件拦截qmake -query调用返回空结果。所以我们必须手动创建 Kit把编译器、Qt 版本、调试器三者精确绑定。3.1 添加 MinGW 编译器指向g.exe而非文件夹进入Tools Options Kits Compilers点击右上角Add GCC MinGWName:MinGW 11.2 64-bit自定义便于识别Compiler path:D:\Qt672\6.7.2\mingw_64\bin\g.exe⚠️ 必须是.exe文件不是文件夹ABI:x86_64-linux-generic-elf-64bit→ 改为x86_64-windows-msvc2019-pe-64bit这是 MinGW 的 ABI 标识Qt Creator 依赖它匹配 Qt 版本点击 OK 后在列表中确认该编译器状态为绿色 ✔️。若为黄色 ⚠️鼠标悬停提示 “ABI mismatch”说明 ABI 填错需重新编辑。3.2 添加 Qt 版本用qmake.exe路径禁用自动探测进入Tools Options Kits Qt Versions点击Add浏览到D:\Qt672\6.7.2\mingw_64\bin\qmake.exe⚠️ 不是qmake.bat也不是文件夹Qt Creator 会自动读取版本号显示为Qt 6.7.2此时务必点击右侧 “Details” 展开确认 “Mkspec” 显示为win32-g。若显示win32-msvc说明你误选了 MSVC 版本的 qmake需删除重选。血泪经验某次我误将D:\Qt672\6.7.2\msvc2019_64\bin\qmake.exe加入 Qt Versions后续 Kit 绑定时一切正常但编译时链接器疯狂报LNK2019: unresolved external symbol __imp__—— 因为 MinGW 编译器无法链接 MSVC 编译的 Qt 库。这个细节必须肉眼核对 “Mkspec”。3.3 创建最终 Kit三要素强制绑定禁用自动继承进入Tools Options Kits Kits点击AddName:Desktop Qt 6.7.2 MinGW 64-bit命名规范方便后续脚本调用Device type:DesktopCompiler: 选择刚添加的MinGW 11.2 64-bitQt version: 选择刚添加的Qt 6.7.2路径含mingw_64Debugger:Auto-detectedQt Creator 12.0 自带 GDB无需额外配置CMake Tool:None首次 demo 不启用 CMake避免干扰点击 OK。此时该 Kit 右侧应显示绿色 ✔️且 “Warning” 栏为空。若出现 “No debugger set” 黄色警告忽略即可GUI 应用调试非首次必需。关键验证动作关闭 Options 对话框在 Qt Creator 主界面右下角状态栏点击 Kit 名称如Desktop Qt 6.7.2...在弹出菜单中确认该 Kit 已被选中前方有对勾。这是后续新建项目生效的前提。4. 新建 Widget Application 并跑通避开 CMake 默认模板强制使用 qmake 构建系统Qt Creator 12.0 默认新建项目使用 CMake但 CMakeLists.txt 对新手极不友好默认启用find_package(Qt6 REQUIRED COMPONENTS Widgets)若 Qt 安装路径不在 CMake 默认搜索路径直接报 “Could not find Qt6Config.cmake”project(MyApp LANGUAGES CXX)隐式要求 C17而某些 MinGW 版本需显式加-stdc17错误信息堆栈长达 50 行新手根本找不到 root cause。所以我们强制使用 qmake 模板——它只有一个.pro文件语法直观错误定位秒级。4.1 创建项目明确选择 qmake禁用 CMakeFile New File or Project Application Qt Widgets ApplicationName:HelloQtDemoPath:D:\QtProjects纯英文路径同前Build system:必须选择qmake下拉框不是默认的 CMakeQt Version: 选择Qt 6.7.2 (Desktop Qt 6.7.2 MinGW 64-bit)即你刚创建的 KitDetails:Class name:MainWindow保持默认Base class:QMainWindow保持默认取消勾选 “Generate form”避免生成.ui文件减少首编译干扰点击Next Finish。项目创建后左侧项目树应显示HelloQtDemo ├── HelloQtDemo.pro ← qmake 配置文件 ├── main.cpp ← 入口函数 ├── MainWindow.h/.cpp ← 主窗口类 └── ...4.2 修改 .pro 文件显式声明 Qt 模块与 C 标准双击打开HelloQtDemo.pro删除所有注释行仅保留并修改为以下内容QT core widgets TARGET HelloQtDemo TEMPLATE app CONFIG c17 SOURCES main.cpp\ MainWindow.cpp HEADERS MainWindow.h关键点说明QT core widgets显式声明依赖模块core是基础widgets是 GUI 组件若漏core编译报QApplication: No such fileCONFIG c17强制启用 C17Qt6 默认要求避免auto、if constexpr报错SOURCES和HEADERS中的反斜杠\后必须跟换行不能有空格否则 qmake 解析失败这是新手最高频的语法坑。4.3 编译并运行观察构建日志定位第一处失败点点击左下角Build Build Project HelloQtDemo或 CtrlB。观察底部Compile Output面板若出现g -c -pipe ...开头的长命令行说明编译器已调用若卡在Running C:\Qt672\6.7.2\mingw_64\bin\qmake.exe ...且无后续说明.pro文件语法错误检查反斜杠和换行若报error: QApplication was not declared in this scope说明QT core漏写。编译成功后点击绿色三角形Run或 CtrlR。首次运行会弹出 Qt Creator 的“Deploy to Desktop”对话框选择 “Run on Desktop” 并勾选 “Always use this device”—— 此设置保存在项目.user文件中避免每次运行都弹窗。现象验证窗口标题应为HelloQtDemo中央无内容因未放控件。此时你已达成目标Qt 安装、Kit 配置、项目构建、二进制运行四步闭环完成。右键任务栏程序图标属性中“目标”字段应显示D:\QtProjects\build-HelloQtDemo-Desktop_Qt_6_7_2_MinGW_64_bit-Debug\debug\HelloQtDemo.exe—— 这是你亲手构建的可执行文件。5. 避坑指南5 个让 80% 新手卡住的致命细节与解法这些不是“可能遇到”的问题而是我在某高校实训课带 37 名学生实操时现场高频复现、且 100% 可复现的硬性陷阱。每一条都附带现象、根因、一招解法拒绝模糊描述。5.1 现象Qt Creator 启动后 Kit 列表为空或显示 “No valid kits found”原因安装时勾选了 Qt 版本但未勾选对应编译器如勾了Qt 6.7.2 MinGW 64-bit却漏了Developer and Designer Tools Qt Creator下的 MinGW 工具链或安装路径含空格qmake 启动时参数解析失败。解法重装 Qt严格按第 2 章路径要求D:\Qt672安装时在组件页展开Qt Qt 6.7.2确认MinGW 11.2 64-bit左侧方框为实心勾选非灰色半选手动验证D:\Qt672\6.7.2\mingw_64\bin\qmake.exe -v是否输出版本号。5.2 现象编译时报错 “The code model could not parse the file” 或 “Cannot open include file: QApplication原因.pro文件中QT 行末尾有多余空格或SOURCES路径中使用了正斜杠/Windows 下 qmake 要求反斜杠\或 Qt 版本绑定错误Kit 中 Qt version 指向了msvc2019_64路径。解法用记事本打开.pro文件显示所有空格和制表符记事本 → 查看 → 显示符号删除QT 行末空格将SOURCES main.cpp MainWindow.cpp改为分行写法见第 4.2 节代码块进入Options Kits Kits点击你的 Kit检查 “Qt version” 路径是否含mingw_64字样。5.3 现象运行后窗口一闪而逝控制台无输出原因main.cpp中QApplication a(argc, argv);后缺少a.exec();或return a.exec();被误删或项目构建套件Build Kit与运行套件Run Kit不一致如构建用 MinGW运行却选了 MSVC Kit。解法打开main.cpp确认最后三行是QApplication a(argc, argv); MainWindow w; w.show(); return a.exec(); // 必须有这一行点击左下角 Kit 名称确认构建和运行使用同一 Kit名称完全一致。5.4 现象点击 Run 后弹出 “Cannot deploy application: No deployment tool configured”原因Qt Creator 将 “Desktop” 设备类型识别为需要部署deploy但 Windows 桌面应用无需部署步骤。解法Projects Build Run Run选项卡找到 “Run configuration” 下拉框选择HelloQtDemo (on Desktop)确保 “Run in terminal” 未勾选GUI 应用不需要终端关键点击右侧 “Add Run Configuration” 旁的齿轮图标 → “Edit Run Configuration” → 将 “Deployment” 设置为None。5.5 现象修改代码后 CtrlS 保存但再次运行仍是旧窗口无变化原因Qt Creator 默认启用增量构建Incremental Build但有时 qmake 未检测到.pro变更或 moc 生成的moc_MainWindow.cpp缓存未更新。解法Build Clean Project HelloQtDemo清除所有中间文件Build Rebuild Project HelloQtDemo全量重建永久方案Projects Build Run Build选项卡 → 勾选 “Always build project before deploying”强制每次运行前构建。6. 进阶验证用一行命令验证 Qt 安装有效性替代 GUI 点击流当你要批量验证 10 台新装机、或写自动化部署脚本时GUI 操作不可靠。下面这个 PowerShell 脚本能在 3 秒内给出 Qt 安装是否“真正可用”的结论——它不依赖 Qt Creator只调用底层工具链且返回值可被 CI/CD 系统直接捕获。6.1 编写验证脚本verify-qt-install.ps1在D:\Qt672目录下新建文件verify-qt-install.ps1内容如下# verify-qt-install.ps1 $QtPath D:\Qt672\6.7.2\mingw_64 $qmake $QtPath\bin\qmake.exe $gpp $QtPath\bin\g.exe # Step 1: Check if tools exist if (-not (Test-Path $qmake)) { Write-Error qmake.exe not found at $qmake; exit 1 } if (-not (Test-Path $gpp)) { Write-Error g.exe not found at $gpp; exit 1 } # Step 2: Verify qmake can query Qt info $qmakeQuery $qmake -query 2$null if ($LASTEXITCODE -ne 0) { Write-Error qmake -query failed; exit 1 } if ($qmakeQuery -notmatch QT_INSTALL_PREFIX.*D:\\Qt672) { Write-Error qmake reports wrong install path; exit 1 } # Step 3: Generate minimal .pro and build $testDir $env:TEMP\qt-verify-$(Get-Random) New-Item -ItemType Directory -Path $testDir | Out-Null Set-Content -Path $testDir\test.pro -Value QT core TARGET qtverify TEMPLATE app SOURCES main.cpp Set-Content -Path $testDir\main.cpp -Value #include QCoreApplication int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); return 0; } # Step 4: Build with qmake make Push-Location $testDir $qmake | Out-Null if ($LASTEXITCODE -ne 0) { Write-Error qmake generation failed; Pop-Location; exit 1 } # Use MinGWs mingw32-make (not system make) $make $QtPath\bin\mingw32-make.exe $make | Out-Null if ($LASTEXITCODE -ne 0) { Write-Error mingw32-make build failed; Pop-Location; exit 1 } # Step 5: Verify binary exists and runs $exePath $testDir\qtverify.exe if (-not (Test-Path $exePath)) { Write-Error Executable not generated; Pop-Location; exit 1 } $exePath | Out-Null if ($LASTEXITCODE -ne 0) { Write-Error Executable crashed; Pop-Location; exit 1 } Pop-Location Write-Host ✅ Qt installation verified successfully at $QtPath -ForegroundColor Green exit 06.2 执行与解读返回值以管理员身份打开 PowerShell执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser .\verify-qt-install.ps1返回0绿色成功提示Qt 安装、编译器、qmake、链接器、运行时全部就绪可投入开发返回1脚本中某步失败错误信息明确指出哪一环断了如 “qmake -query failed” 说明环境变量或权限问题“mingw32-make build failed” 说明 MinGW 工具链损坏返回2PowerShell 执行策略阻止按提示执行Set-ExecutionPolicy即可。我的习惯把这个脚本加入公司新员工入职 checklist要求每人提交执行成功的截图。它比“截图 Qt Creator 界面”可靠 10 倍——因为 GUI 可能只是缓存了旧配置而这个脚本强制走通了从源码到二进制的全链路。有一次发现 3 台机器qmake -query返回空追查是杀毒软件把qmake.exe当可疑进程拦截了GUI 完全无提示而脚本秒级暴露。希望帮到你。本文还有配套的精品资源点击获取