新建Qt Widgets Application时须选对模板、用纯英文无空格路径、不跳过Kit选择，否则qmake报Unknown module(s) in QT: widgets；基类选QMainWindow并勾选Create form，确保生成.ui文件供Designer编辑。
直接新建 Qt Widgets Application 就行，别选错模板、别用空格和中文路径、别跳过 Kit 选择——这三步踩错一个，qmake 就会报 Unknown module(s) in QT: widgets 或直接编译失败。
选对模板：必须是 Qt Widgets Application
Qt Creator 欢迎页或菜单栏点 File → New File or Project 后，在模板列表里只认准这一项：Application → Qt Widgets Application。它生成的是基于 QMainWindow / QWidget 的传统桌面窗口程序，自带 .ui 文件和信号槽基础结构。其他选项比如 Qt Quick Application 用的是 QML，Console Application 根本不带窗口，新手硬上等于从悬崖起步。
常见错误现象：
- 选了
Empty qmake Project：手动补全QT += widgets都可能漏掉CONFIG += c++17，QPushButton构造失败 - 选了
Qt Console Application：代码里写QMainWindow window; window.show();也没用，链接器找不到 GUI 模块入口
填项目信息时盯住两个硬约束
项目名称和路径必须满足：纯英文、无空格、无中文、无特殊字符（如 !、(、~）。比如 my_first_qt_app 可以，我的第一个Qt程序 或 hello world 会触发 uic 工具解析 .ui 文件失败，报错类似 error: cannot open input file '中文路径/mainwindow.ui'。
Kit 选择不能跳过。安装完 Qt 后，Creator 通常自动检测出一个带 MinGW（Windows）或 Clang 64-bit（macOS）的 Kit。如果列表为空，说明 Qt 版本没装好，或安装时没勾选对应编译器组件——此时点 Add 手动指定 qmake 路径（如 C:\Qt\5.15.2\mingw81_64\bin\qmake.exe）比硬着头皮往下走更省时间。
基类和 UI 文件勾选有默认最优解
创建过程中会问“Base class”和“Generate form”。对第一个程序，按这个组合来：
-
Base class选QMainWindow：它自带菜单栏、状态栏占位区，后续加菜单/工具栏不用重构 - 务必勾选
Create form：生成mainwindow.ui，这样你才能双击打开 Qt Designer 拖按钮、改文字，而不是纯手写布局代码
不勾选 Create form 看似“轻量”，实则逼你手动在 mainwindow.cpp 里调用 new QLabel、new QVBoxLayout，初学阶段极易因 setParent() 漏写或布局未 addWidget() 导致控件不显示。
运行前确认 main.cpp 里没删关键两行
生成的 main.cpp 默认长这样：
#include <qapplication>
#include <qmainwindow>
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
QMainWindow window;
window.show();
return app.exec();
}
</qmainwindow></qapplication>
只要没手动删掉 app.exec()，窗口就能弹出来。但注意：这只是空白窗口。真正显示 “Hello World!” 和按钮，得去 mainwindow.ui 里拖控件，或在 MainWindow 构造函数里写逻辑。很多新手卡在“程序能跑但窗口是空的”，其实是误以为 main.cpp 负责所有界面内容——它只管启动框架，界面归 mainwindow.* 管。
容易被忽略的地方：macOS 上首次运行若弹窗提示“已损坏，无法打开”，不是代码问题，是系统安全策略。需要右键 App → “显示简介” → 勾选“仍要打开”。这个提示不会重复出现，但第一次必然遇到。
