3、第一个Qt程序：创建项目、理解main.cpp、QApplication、QWidget、窗口显示、编译运行与调试

从零开始编写第一个Qt程序，是理解Qt框架运行机制的最佳切入点。很多初学者习惯直接使用Qt Creator的“新建项目”向导，点击“运行”看到窗口弹出后便认为已经入门，但实际上对项目结构、对象生命周期和事件循环缺乏本质理解。本章将带领你手动走完从创建项目到调试运行的完整链路，重点剖析main.cpp中每一行代码背后的含义，并建立对QApplication与QWidget协作关系的清晰认知。通过本章学习，你将具备独立搭建最小Qt工程、定位启动阶段常见错误的能力。

上图展示了从main.cpp源码到窗口显示的核心链路。整个流程可以概括为：创建QApplication对象 → 创建QWidget窗口 → 调用show()显示窗口 → 进入事件循环。其中，QApplication负责管理应用程序级别的资源与事件分发，而QWidget则代表一个可交互的窗口单元。理解这条链路，是后续学习信号槽、布局管理、自定义控件的基础。

3.1 创建项目：手动构建与Qt Creator向导

3.1.1 核心原理：项目文件的作用

Qt项目通常使用.pro文件（qmake）或CMakeLists.txt（CMake）来描述构建规则。这些文件告诉编译器：源文件有哪些、需要链接哪些Qt模块、生成的目标名称是什么。对于初学者，推荐先使用Qt Creator的“新建项目”向导，但必须理解向导生成的每个文件的作用。

# myapp.pro
QT += core gui
greaterThan(QT_MAJOR_VERSION, 4): QT += widgets
TARGET = myapp
TEMPLATE = app
SOURCES += main.cpp

QT += core gui声明使用核心与GUI模块；greaterThan(...)是Qt 5及以上版本需要添加widgets模块的兼容写法；TARGET指定生成的可执行文件名；TEMPLATE = app表示生成应用程序。

3.1.2 操作流程：使用Qt Creator创建项目

1. 打开Qt Creator，选择“文件” → “新建项目” → “Application” → “Qt Widgets Application”。
2. 设置项目名称（如MyFirstQt）和保存路径，注意路径不要包含中文或空格。
3. 选择构建套件（Kit），通常选择已配置好的Desktop Qt版本。
4. 向导会自动生成main.cpp、mainwindow.cpp、mainwindow.h、mainwindow.ui以及.pro文件。
5. 点击“构建”按钮（锤子图标），观察“编译输出”面板，确认无错误。

3.1.3 案例拆解：从空文件到可运行窗口

假设你手动创建了一个文件夹first_qt，里面只有两个文件：main.cpp和first_qt.pro。在main.cpp中输入以下代码：

#include <QApplication>
#include <QWidget>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    QWidget window;
    window.setWindowTitle("我的第一个Qt程序");
    window.resize(400, 300);
    window.show();
    return app.exec();
}

在first_qt.pro中写入：

QT += core gui widgets
TARGET = first_qt
TEMPLATE = app
SOURCES += main.cpp

然后在终端执行qmake和make（Linux/macOS）或使用Qt Creator打开.pro文件构建。运行后，一个400×300像素、标题为“我的第一个Qt程序”的窗口将出现在屏幕上。

3.1.4 常见误区与复盘

• 误区1：忘记添加widgets模块，导致QWidget未定义。Qt 5及以上版本必须显式声明QT += widgets。
• 误区2：项目路径包含中文或空格，导致编译链接失败。Qt工具链对路径中的非ASCII字符支持不完善。
• 误区3：认为main.cpp中必须包含QMainWindow。实际上QWidget完全可以作为主窗口，只是缺少菜单栏、状态栏等高级布局。

3.2 理解main.cpp：QApplication与QWidget的协作

3.2.1 核心原理：QApplication的角色

QApplication是Qt GUI程序的“总管家”。它负责：

• 初始化Qt运行环境（字体、样式、剪贴板等）。
• 管理事件循环，将系统消息（鼠标点击、键盘输入）转换为Qt事件。
• 控制应用程序的全局状态，如setStyle()、setQuitOnLastWindowClosed()。

每个Qt GUI程序必须有且仅有一个QApplication实例，且必须在创建任何QWidget之前创建。

3.2.2 判断方法：代码执行顺序

观察以下代码的执行顺序：

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);  // 第1步：创建应用对象
    QWidget window;                 // 第2步：创建窗口对象
    window.show();                  // 第3步：显示窗口（但此时还未进入事件循环）
    return app.exec();              // 第4步：进入事件循环，程序在此阻塞
}

第3步的show()只是将窗口标记为可见，但窗口的绘制和交互需要事件循环启动后才能正常进行。第4步的exec()是一个无限循环，直到调用quit()或关闭最后一个窗口才返回。

3.2.3 案例拆解：窗口显示背后的机制

当show()被调用时，Qt会向窗口发送一个“显示事件”（QShowEvent），但此时事件循环尚未启动，事件被放入队列。当exec()启动后，事件循环从队列中取出事件并分发处理，窗口才真正绘制到屏幕上。这也是为什么在show()之后、exec()之前添加QThread::sleep(2)不会看到窗口延迟出现——因为事件循环还没开始。

3.2.4 常见误区与总结

3.3 编译运行与调试：从构建到排障

3.3.1 核心原理：构建系统的三个步骤

Qt程序的构建过程分为：qmake生成Makefile → make编译链接 → 运行可执行文件。Qt Creator将这三步封装为“构建”和“运行”按钮。调试时，需要额外启动调试器（如GDB或CDB），并设置断点。

3.3.2 操作流程：使用Qt Creator调试

1. 在main.cpp的QApplication app(argc, argv);行左侧点击，添加断点（红色圆点）。
2. 点击“调试”按钮（绿色虫子图标），程序将在断点处暂停。
3. 在“变量”面板中查看app对象的属性，确认其已正确初始化。
4. 按F10单步执行，观察window对象的创建过程。
5. 在window.show()处添加断点，执行后检查窗口是否可见（isVisible()属性）。

3.3.3 案例拆解：窗口不显示的排障过程

背景：某学员在Windows上运行程序，控制台无报错，但窗口不出现。

初始现象：程序运行后，任务栏有进程，但桌面无窗口。

关键日志/指标：调试输出无异常，app.exec()正常返回。

分析判断：可能原因包括：窗口被创建但未调用show()；窗口尺寸为0；窗口被其他窗口遮挡。

实际操作：

1. 检查代码，确认调用了window.show()。
2. 在show()后添加qDebug() << window.size();，输出为QSize(0, 0)。
3. 发现未调用resize()，窗口默认大小为0×0，因此不可见。
4. 添加window.resize(400, 300);后，窗口正常显示。

结果对比：修复前窗口不可见，修复后窗口正常显示。

复盘经验：QWidget默认大小是0×0，必须显式设置尺寸或使用布局管理器。调试时优先检查窗口的size()和isVisible()属性。

3.3.4 常见误区与总结

• 误区1：认为编译通过就代表程序正确。编译只检查语法，不检查逻辑。
• 误区2：调试时只设置断点，不观察变量值。断点只是暂停，必须结合“变量”面板和“调用栈”面板分析。
• 误区3：忽略“应用程序输出”面板中的警告信息。例如“QWidget: Must construct a QApplication before a QWidget”是典型的顺序错误提示。