新建qt widgets application时须选qmainwindow而非qwidget或qdialog，因其自带centralwidget和菜单栏占位，拖控件可见；若误选qwidget则因缺布局和父容器导致控件消失；.pro文件需显式声明qt += core gui widgets（qt6必需），改后须执行qmake；ui控件必须在designer中设置非空objectname，且与代码中ui->xxx严格一致，否则无法访问。
装完就能写代码，但得先绕过几个默认陷阱——比如默认套件不匹配、.pro 文件里缺模块、UI 文件没自动关联类。
新建 Qt Widgets Application 时选错基类会卡死后续开发
选 QMainWindow 而不是 QWidget 或 QDialog，除非你明确要做无菜单栏的弹窗或纯容器。Qt Creator 默认给的模板里，QMainWindow 自带 centralWidget 和菜单/工具栏占位，拖控件进去不会“看不见”。如果误选 QWidget，UI 设计器里拖按钮可能直接消失——因为没设置布局，也没父容器撑开空间。
- 检查
mainwindow.ui是否被正确加载：构造函数里必须有ui->setupUi(this) - 如果 UI 改了但运行没变化，右键
mainwindow.ui→ “重新运行 uic”，强制刷新头文件 -
QDialog适合做登录框、设置页这类模态窗口；它默认无最大化/最小化按钮，也不支持setCentralWidget
编译报错 “Unknown module(s) in QT: widgets”
这是 .pro 文件漏写模块声明导致的，尤其在 Qt6 下更严格。Qt5 默认隐式包含 widgets，Qt6 必须显式声明。
- 打开项目根目录下的
xxx.pro文件，在QT += core gui后面补上widgets：QT += core gui widgets
- 如果用了
QtSerialPort或QtCharts，也得手动加：QT += serialport charts - 改完
.pro文件后，点击左下角“构建” → “执行 qmake”，否则修改不生效
UI 设计器拖完控件，代码里访问不到 ui->xxxButton
根本原因只有两个：控件没起名，或者名字和代码里写的不一致。
- 在 Designer 左侧属性编辑器里，确认
objectName不是空的（比如设为pushButton，别留默认的pushButton_2） - 生成的
ui_mainwindow.h里变量名完全按objectName来，大小写、下划线都必须一模一样 - 不要手敲
ui->pushButton_2->setText(...)，先在 Designer 里双击控件改名，再切回编辑模式写代码 - 如果改名后编译报“no member named 'xxx'”，删掉 build 目录重构建——旧的
ui_*.h没更新
真正卡住新手的不是语法，而是 Qt Creator 把配置分散在四个地方：套件选择器、.pro、UI 属性面板、构建步骤。改一处，常要同步动另外三处，漏一个就白忙活半小时。
