一、认识 Qt SDK 的目录结构

二、第一个 Qt 程序

2.1 Qt Creator 创建项目

2.2 介绍项目各文件

三、揭秘 Qt 的构建过程

四、运行项目与总结

🎬 攻城狮7号：个人主页

🔥 个人专栏:C++QT跨平台界面编程

⛺️ 君子慎独!

🌈 大家好，欢迎来访我的博客！
⛳️ 此篇文章主要介绍 Qt SDK 的目录和第一个Qt Creator项目
📚 本期文章收录在《C++QT跨平台界面编程》，大家有兴趣可以自行查看！
⛺️ 欢迎各位 ✔️ 点赞 👍 收藏 ⭐留言 📝！

一、认识 Qt SDK 的目录结构

在我们开始创建项目之前，先花点时间了解一下 Qt SDK 安装后的目录结构是很有帮助的。这能让你明白编译、链接和运行一个 Qt 程序时，那些必要的文件都来自哪里。

以一个典型的 Qt 安装目录为例（比如 `C:\Qt\Qt5.9.0`），你会看到几个关键的子目录：

进去5.9 目录，会看到`msvc2015_64` / `mingw53_32` 等，这些是以 "编译器_平台" 命名的目录，是你为特定平台开发时真正用到的核心。其中Src是QT源码目录。

每个这样的目录里都包含：

（1）`bin`: 存放着可执行文件和动态链接库（DLL）。这里面不仅有你程序运行时依赖的 `Qt5Core.dll`、`Qt5Gui.dll` 等，还有 Qt 开发工具链三剑客：`qmake.exe`（处理.pro文件生成Makefile）、`moc.exe`（元对象编译器）和 `uic.exe`（UI编译器）。Qt Designer (`designer.exe`) 和 Qt Assistant (`assistant.exe`，用于查阅官方文档) 也在这里。

Qt Designer的功能：可视化 UI 设计工具，通过拖拽组件（按钮、文本框等）快速创建界面，生成.ui文件。

Qt Assistant的功能：集成式文档浏览器，提供 Qt 框架的官方文档、示例代码和 API 参考。

（2） `include`: 存放所有 Qt 模块的头文件（`.h`）。你在代码中 `#include <QWidget>` 时，编译器就是在这里找到对应的文件。

（3） `lib`: 存放库文件（`.lib`）。链接器在生成最终可执行文件时，需要这些文件来解析 Qt 的函数调用。

简单来说，你在 Qt Creator 中选择一个"Kit"（构建套件，例如 `Desktop Qt 5.9.0 MSVC2015 64bit`），实际上就是指定了使用哪个编译器目录下的 `bin`, `include`, `lib` 来编译和链接你的项目。

下面是其他几个主要的5.9 的同级目录：

（1）`plugins`: 存放各类插件。比如，让你的程序能显示 JPG、GIF 图片的图像格式插件，或者连接 MySQL、SQLite 数据库的驱动插件。发布程序时，往往需要把用到的插件（通常是整个目录）一并打包。

（2）`Tools`: 包含了一些工具，比如 Qt Creator IDE 本身，以及可能的第三方编译器套件（如 MinGW）。

（3）`Examples`: 包含了大量的官方示例项目源码，是学习 Qt 非常好的参考资料。

（4）`Docs`: 存放着 Qt 的所有离线帮助文档。

二、第一个 Qt 程序

2.1 Qt Creator 创建项目

现在我们用 Qt Creator 创建一个最基础的 Qt Widgets 应用，首先是打开通过C:\Qt\Qt5.9.0\Tools\QtCreator\bin\qtcreator.exe 双击打开Qt Creator，或者在快速启动栏点击打开。按如下新建项目：

如下选择项目类型：

如下填入项目名称和路径，路径最好是英文。然后下一步

如下只选择一个编译环境

下一步自定义各文件，文件名称最好都是小写，避免代码迁移到linux平台，区分大小的不小心容易出错

如下便创建好了项目

其中widget.ui文件可以双击打开，如下拖放一个按钮控件上去，点击编辑模式，可以看到其ui代码

如下是上面的项目testqt源码文件：

2.2 介绍项目各文件

（1） `.pro` - 项目配置文件

这是一个项目（Project）文件，由 qmake 工具处理。它告诉 Qt 要如何编译你的项目。

QT       += core guigreaterThan(QT_MAJOR_VERSION, 4): QT += widgetsTARGET = testqtTEMPLATE = appSOURCES += main.cpp widget.cppHEADERS += widget.hFORMS += widget.ui

* `QT += core gui widgets`：声明项目需要用到 Qt 的核心、GUI 和窗口部件模块。qmake会据此去`lib`目录和`include`目录引用对应的库和头文件。

* `TARGET = testqt`：指定生成的可执行程序的名字。

* `TEMPLATE = app`：指定这是一个应用程序（app）项目。

* `SOURCES`、`HEADERS`、`FORMS`：分别列出了项目包含的源文件、头文件和界面文件。qmake会根据这些清单来决定哪些文件需要被编译，哪些需要被`moc`或`uic`处理。

（2）`.pro.user` - 用户配置文件（重要概念）

在你的项目目录下，还会看到一个 `testqt.pro.user` 文件。这个文件非常重要，但它不应该被包含在版本控制中（如 Git）。

它存储的是你本地开发环境的配置，比如你选择了哪个 Qt 版本和编译器（即哪个 Kit），以及你的项目构建目录在哪里等等。当你把项目发给别人时，应该删掉这个文件。对方用他的 Qt Creator 打开 `.pro` 文件时，会自动生成一份适合他自己环境的 `.pro.user` 文件。

（3） `main.cpp` - 程序入口

和所有 C++ 程序一样，`main` 函数是程序的起点。

#include "widget.h"
#include <QApplication>int main(int argc, char *argv[]){// 1. 创建 QApplication 实例，它是 Qt 程序的管理者QApplication a(argc, argv);// 2. 创建我们自己的窗口类 Widget 的实例Widget w;// 3. 显示窗口w.show();// 4. 进入事件循环，等待用户操作 (如点击鼠标、按下键盘)return a.exec();}

这个文件很固定，对于大部分应用来说，你几乎不需要修改它。

（4） `widget.h` & `widget.cpp` - 窗口的定义与实现

这两个文件定义了我们主窗口的行为。

`widget.h` (头文件 - 声明)

#ifndef WIDGET_H
#define WIDGET_H#include <QWidget>namespace Ui {
class Widget;
}class Widget : public QWidget
{Q_OBJECT // 重点：Qt 的"魔法"宏，使用信号与槽必须包含它public:explicit Widget(QWidget *parent = 0);~Widget();private:Ui::Widget *ui; // 重点：指向界面设计的指针
};#endif // WIDGET_H

* `class Widget : public QWidget`：我们的窗口类 `Widget` 继承自 Qt 的基础窗口部件 `QWidget`。

* `Q_OBJECT`：一个特殊的宏。只要你想在类中使用 Qt 强大的"信号与槽"机制，就必须加上它。`moc`工具会专门处理它。

* `Ui::Widget *ui;`：这是一个关键的指针。它指向由 `widget.ui` 文件生成的那个界面。通过 `ui` 指针，我们就可以在 C++ 代码中访问界面上的所有元素（比如按钮、输入框等）。

`widget.cpp` (源文件 - 实现)

#include "widget.h"
#include "ui_widget.h" // 重点：包含了 .ui 文件编译后生成的头文件Widget::Widget(QWidget *parent) :QWidget(parent),ui(new Ui::Widget)
{// 这行代码将 .ui 文件中设计的界面和当前的 C++ 代码"关联"起来ui->setupUi(this);
}Widget::~Widget()
{delete ui;
}

* `ui->setupUi(this);` 是最重要的部分。它会读取 `.ui` 文件内容，并将其中设计的按钮等控件实例化，把它们"画"在 `Widget` 这个窗口上。

（5） `widget.ui` - 界面设计文件

这是一个 XML 文件，用 Qt Creator 的设计模式打开时，你可以通过拖拽的方式来设计界面。

<?xml version="1.0" encoding="UTF-8"?>
<ui version="4.0"><class>Widget</class><widget class="QWidget" name="Widget"><property name="geometry"><rect><x>0</x><y>0</y><width>671</width><height>478</height></rect></property><property name="windowTitle"><string>Widget</string></property><widget class="QPushButton" name="pushButton"><property name="geometry"><rect><x>230</x><y>170</y><width>191</width><height>101</height></rect></property><property name="text"><string>PushButton</string></property></widget></widget><layoutdefault spacing="6" margin="11"/><resources/><connections/>
</ui>

可以看到，我们在界面上放了一个 `QPushButton`，它的 `name` 是 `pushButton`，显示的文本是 `PushButton`。在 C++ 代码中，我们就可以通过 `ui->pushButton` 来访问这个按钮。

三、揭秘 Qt 的构建过程

当你点击"运行"按钮时，Qt Creator 在背后为你做了几件重要的事情，最终才生成了可执行文件。这个过程通常发生在一个单独的构建目录中（比如 `build-testqt-Desktop_Qt_5_9_0...`）。

（1）`qmake` 生成 Makefile：`qmake.exe` 首先读取你的 `testqt.pro` 文件。根据里面的配置，它会生成一个 `Makefile`（以及 `Makefile.Debug` 和 `Makefile.Release`）。Makefile 是一个构建规则文件，它精确定义了接下来需要执行的所有编译和链接命令。

（2）`uic` (User Interface Compiler) 编译 UI 文件：在编译过程中，`uic.exe` 会被调用。它读取 `widget.ui` 这个 XML 文件，并把它转换成一个标准的 C++ 头文件，名为 `ui_widget.h`。这个头文件里定义了 `Ui::Widget` 类，并包含了创建所有界面控件（如 `pushButton`）的代码。这个文件也被生成在构建目录中。

（3）`moc` (Meta-Object Compiler) 处理元对象：接下来，`moc.exe` 会扫描你所有声明了 `Q_OBJECT` 的头文件（这里是 `widget.h`）。它会为这个类生成一些额外的 C++ 代码（保存在 `moc_widget.cpp` 中），用于实现信号与槽等高级功能。

（4）C++ 编译器编译所有源文件：最后，你的 C++ 编译器（如 MSVC 或 MinGW）会编译所有的 `.cpp` 文件，这包括：

* 你自己写的 `main.cpp` 和 `widget.cpp`。

* 由 `moc` 生成的 `moc_widget.cpp`。

（5）链接器生成可执行文件：编译器将所有源文件编译成目标文件（`.obj`）后，链接器会把这些目标文件与 Qt 库（`.lib` 文件）链接起来，最终生成 `testqt.exe` 这个可执行文件。

了解这个过程有助于你排查一些奇怪的编译错误。比如，如果你修改了 UI 文件但表现不正确，可能是 `uic` 没有重新运行；如果信号槽不工作，有时是 `moc` 过程出了问题。这时，执行一次"清理项目"再"重新构建"通常能解决问题。