Qt6+CMake实战：从零搭建第一个工程完整指南

说实话，每次看到有人还在用 qmake 搭全新的 Qt 项目，我都想按住他的手说一句：该换 CMake 了。Qt6 发布之后，官方几乎把所有示例、插件、工具链都迁到了 CMake 体系里，连 Qt Creator 新建向导默认生成的构建系统都是 CMake。很多从 Qt5 时代或 qmake 模板入门的朋友，第一次打开 Qt6 的 CMakeLists.txt 会觉得陌生，满屏的 find_package、qt_add_executable、AUTOMOC 看得发懵。这篇文章就是我跑通第一个 Qt6 + CMake 工程的全过程复盘。从环境准备、目录设计、CMake 配置，到命令行构建、IDE 调试、常见报错，全部按实操顺序走一遍。适合刚接触 Qt6 的初学者，也适合从 qmake 迁移过来的老手快速踩平落地。

1. 为什么第一个工程必须用 CMake 来搭

1.1 Qt6 全面转向 CMake 的现实

先捋一下时间线。Qt6 正式发布后，官方维护的构建工具链核心从 QMake 切换到了 CMake，这一点不是口号，而是细节里的实锤：官方示例源码统一使用 CMakeLists.txt，Qt 模块的导出和命名空间全面对接 CMake target，新出的工具如 qt_add_resources、qt_add_qml_module 也都是 CMake 函数。

qmake 并没有立刻消失，Qt6 仍然带 qmake 支持，但它的地位已经从主力变成了兼容层。QMake 的 .pro 语法在小型 demo 里写着确实省事，可一旦工程多目录、需要条件编译、要对接第三方库时，qmake 的变量系统就会变得难以维护。CMake 的 target 概念让依赖关系更明确，Qt6::Widgets这种东西一写出来，谁链接了谁一目了然。

我个人的体会是，用 CMake 还有一些隐性收益。CI 环境下用 CMake 做打包和交叉编译的方案已经非常成熟，后续你要接 GitHub Actions、内部构建服务器，CMake 的脚本就是现成的底气。就算你现在只写一个 Window 上的小工具，用 CMake 起步也不会亏。

1.2 从下颌到顺畅：放弃手工编译参数

很多 Qt 初学者的第一个瓶颈其实不是写代码，而是编译。Qt 的头文件、库文件、动态链接库、moc 生成的元对象代码，这些都需要构建系统自动去发现和处理。qmake 能帮你做这些，但它对工程的控制粒度比较粗。

CMake 的做法是显式声明。你把源码文件、依赖、目标告诉 CMake，它负责找 Qt 的库路径、处理 UIC 和 MOC 的生成步骤。Qt6 里的 qt_standard_project_setup() 会帮你把这些繁重的规则都设置好，包括自动启用 AUTOMOC 和 AUTOUIC。这就像从手写 HTML 标签过渡到了用模板框架，不需要自己惦记每个细节。

我在迁移一个旧工程时的经验是：CMake 第一次配置大概会慢一点，因为它要扫描编译器、解析 Qt 的 CMake 配置文件，但之后的增量构建速度是明显优于 qmake 的。更重要的是，CMake 的 configure 阶段像一面镜子，能提前把链接库缺失、头文件路径不对这类错误暴露出来，而不是等到编译到一半才炸。

2. 跑通之前的准备工作：环境选型

2.1 开发环境组件清单

在写第一个 CMake 工程之前，先确认几个必要组件，避免跑到一半发现缺东西。下表是我整理的最小环境清单：

其中 Qt 6.4 开始对 CMake 3.16 以上有明确要求，但如果你的 CMake 版本太老，会发现很多 Qt 示例里用到的qt_standard_project_setup()或qt_add_executable()的行为和预期不一致。我建议直接装 CMake 3.22 之后的版本，否则一些新特性的表现会受限制。其次是编译器，Windows 上最推荐 MSVC，因为 Qt 官方仓库默认发布的预编译库就是 MSVC 版本，和你的项目编译器匹配度最高；如果要用 MinGW，请确认你下载的 Qt 包也是 MinGW 版本，混用会导致链接阶段离奇报错。

2.2 Qt6 安装时需要注意的选项

从 Qt 官网下载在线安装器之后，很多人会盯着组件列表发呆。第一次装 Qt6，如果你只做桌面 Widgets 程序，其实不需要勾选全部组件，那会让安装体积巨大。最低限度下，展开 Qt 6.x 目录，选择Qt 6.x.x下与你的编译器匹配的子项即可，比如MSVC 2019 64-bit或MinGW 11.2.0 64-bit。另外建议勾选Debugger和CMake相关工具，Qt 在线安装器自带的 CMake 版本通常够用。

安装时有一个容易忽略的细节：Qt 库本身会被拆成多个模块，比如Qt 6.8下还有Qt 5 Compatibility Module之类的可选组件。如果你暂时只写新代码，不需要兼容 Qt5，那么默认的 Qt 6 Desktop 组件已经含了 Core、Gui、Widgets，完全能满足入门。我在第一次安装时贪心勾选了很多组件，结果下载了几个 GB，实际用到的不到三分之一。建议先装最小集合，跑通第一个工程，之后缺什么再补装，这比一开始全量构建要高效很多。

2.3 编译器和构建环境的快速自检

装完环境别急着写代码，先做一次快速自检。因为 Qt 对编译器的依赖很强，如果工程一直报一些奇怪的链接错误，很可能是编译器选择和 Qt 包不匹配。

打开终端（Windows 上推荐用 Qt 自带的命令提示符入口，或者普通终端但先进入 MSVC 环境），执行：

cmake --version

确认 CMake 版本没问题后，再检查编译器：

cl # 检查 MSVC g++ # 检查 MinGW

如果是 MinGW，可以用gcc --version看版本号。Qt6 对 C++17 有硬性要求，如果你的 GCC 版本低于 9，建议还是换新版本或者直接换 MSVC，否则后续可能遇到各种奇怪的模板编译错误。还有一个小技巧：在终端里执行qmake -v（如果你的 Qt bin 目录在 PATH 里），可以查看 Qt 对应的构建工具和目录路径，但这里我不依赖它，因为后面我们用 CMake 去定位 Qt，更规范也更灵活。

3. 创建第一个工程：目录与源码

3.1 工程目录怎么规划才不凌乱

很多新手建工程时习惯把所有源码放在根目录，这在小 demo 里没问题，但后续扩展会很痛苦。我的建议是哪怕第一个 CMake 工程，也要做最简单却良好的目录分层：

MyFirstQtApp/ ├── CMakeLists.txt ├── src/ │ └── main.cpp └── build/

这里把源码放在src/下，是为了给后续增加新源文件留出空间。你也可以直接平铺，比如根目录放main.cpp，因为 Qt 官方示例就是这么做的。但使用src/子目录能让你更早养成模块化习惯。build/目录专门放构建产物，不会污染源码目录。用 CMake 时通常不需要手动创建 build 目录，在配置时指定即可，它会自动创建。

我看到有人喜欢把构建目录放在工程外甚至系统临时目录，比如build-release、build-debug这种按构建类型命名的方式。这在只跑单配置生成器（比如 Ninja）时尤其有用，因为你切换 Debug / Release 时实际上需要重新配置一个目录。我之后会单独讲怎么管理多构建目录，第一个工程可以先只用一个build。

3.2 写一个能跑的最小 main.cpp

既然工程目标是跑通，源码就写最经典的窗口程序：打开一个窗口，里面显示一行文字。不用引入复杂业务逻辑，纯粹的验证链路。

在src/main.cpp里写：

#include <QApplication> #include <QLabel> int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label("Hello, Qt6 and CMake!"); label.resize(400, 300); label.show(); return app.exec(); }

这段代码本身没什么好说的。有一个细节需要注意：在 Qt6 里，QApplication和QLabel都来自 Widgets 模块，如果你的头文件路径没配置好，#include <QApplication>会直接报找不到头文件。所以我们接下来要做的 CMake 配置，核心目的之一就是让编译器知道这些头文件是哪里的、对应的库文件在哪里。

其实你也可以试试用QPushButton或QLineEdit，效果一样。重要的是通过这十几行代码验证整个构建链路，而不是代码本身有多复杂。有人会直接把app.exec()的返回值作为 main 的返回值，也行，我习惯显式return app.exec()，意图更明确。

4. CMakeLists.txt 核心配置逐行拆解

4.1 版本声明与工程名

第一个工程的CMakeLists.txt看起来不长，但每一行背后都有讲究。我先把完整内容贴出来，再逐行说明：

cmake_minimum_required(VERSION 3.16) project(MyFirstQtApp VERSION 1.0 LANGUAGES CXX) find_package(Qt6 REQUIRED COMPONENTS Widgets) qt_standard_project_setup() qt_add_executable(MyFirstQtApp src/main.cpp ) target_link_libraries(MyFirstQtApp PRIVATE Qt6::Widgets)

第一行cmake_minimum_required(VERSION 3.16)代表这个工程至少需要 CMake 3.16。Qt6 官方最低要求一般是 3.16，但实际编译时，如果你的 CMake 版本低于 3.21，qt_standard_project_setup()或qt_add_executable()的部分行为可能会退化。更稳妥的是写成 3.22 或 3.25，避免因为版本太老踩到兼容性的坑。我自己的工程里一般写：

cmake_minimum_required(VERSION 3.22)

以此确保 CMake 的新特性都能正常启用。

project(MyFirstQtApp VERSION 1.0 LANGUAGES CXX)这行除了设置工程名，还指定了语言是 C++。不写LANGUAGES CXX的话，CMake 默认也会检测 C 和 CXX，但显式声明更清晰，也能避免某些环境下误探测到 C 编译器导致不必要的配置问题。工程名MyFirstQtApp和qt_add_executable里的目标名可以不重名，但建议保持一致，以便生成的执行文件名直观可认。

4.2 find_package 与 Qt 组件解析

find_package(Qt6 REQUIRED COMPONENTS Widgets)是整份 CMakeLists 的命脉。它帮助 CMake 在系统中定位 Qt6 的 CMake 配置文件和库文件。REQUIRED表示如果找不到 Qt6，就直接报错，不继续执行。COMPONENTS Widgets表示我们只需要 Widgets 模块。

这里需要展开讲一个核心点：find_package找的是什么？它找的是 Qt6 安装目录下lib/cmake/Qt6/Qt6Config.cmake这个文件，通过它 CMake 才能知道 Qt6 的完整布局。为什么我们要强调这一点呢？因为如果安装 Qt 时只给了 Qt Creator 一个路径，而没有告诉 CMake，那么 CMake 在系统默认路径里找不到 Qt6，就会报出非常经典的错误：Could not find a package configuration file。解决方案是后面会提到的CMAKE_PREFIX_PATH。

关于组件，很多人会好奇：我只用了QLabel，为什么不能只find_package(Qt6)不写组件？事实上 Qt6 的核心模块如 Core、Gui 被 Widgets 依赖，你只写COMPONENTS Widgets就能自动把这些依赖带上，但最好还是显式一点。如果后续你要用到Qt6::Network、Qt6::Sql或Qt6::Qml，就要在 COMPONENTS 里追加对应名字。例如：

find_package(Qt6 REQUIRED COMPONENTS Widgets Network)

这个配置直接影响后面target_link_libraries能使用哪些库 target。

4.3 qt_standard_project_setup 自动帮你做了什么

qt_standard_project_setup()是 Qt6 引入的便捷函数。以前在 Qt5 里，为了让 Qt 能自动处理头文件的 moc 扫描，你得手动设置：

set(CMAKE_AUTOMOC ON) set(CMAKE_AUTOUIC ON) set(CMAKE_AUTORCC ON)

而在 Qt6 里，qt_standard_project_setup()一行就能把这些开关全部打开。它还做了额外的事情：设置CMAKE_CXX_STANDARD为 Qt 需要的标准（通常是 17 或更高），并设置了某些与 Qt 资源系统相关的变量。如果你的工程只写 Widgets 程序且没有 .ui 和 .qrc，这行似乎有点多余，但它能让工程在接入更多 Qt 功能时不踩坑，所以建议保留。

有一类非常隐蔽的报错，就是忘记写qt_standard_project_setup()，而工程里又存在含有Q_OBJECT宏的头文件，结果编译时出现一堆undefined reference to vtable错误。可如果你用了这行配置，这个坑就被自动绕过了。这也是为什么我强烈建议新工程直接采用 Qt6 推荐的这套 CMake 函数，而不是沿用老的add_executable加手动set(CMAKE_AUTOMOC ON)的写法。

4.4 qt_add_executable 与旧有什么不同

在 CMake 里，创建一个可执行目标的标准写法是：

add_executable(MyFirstQtApp src/main.cpp)

在 Qt6 官方示例和项目模板里，你看到的常常是qt_add_executable(...)。这个函数是 Qt6 对add_executable的封装，虽然本质上也是生成一个可执行目标，但它多做了几件事：它会自动处理与 Qt 相关的源文件属性，比如在你想将 QML 模块引入工程时，qt_add_executable能帮你正确设置 QML 导入路径。此外，在qt_add_executable之后，你还可以用相同目标名去调用其他 Qt 相关函数，比如qt_add_qml_module、qt_add_resources，这种目标管理思路是 Qt6 推荐的。

不过要注意一点：qt_add_executable存在的前提是你已经find_package(Qt6)。这很自然，因为它是 Qt 提供的函数。如果 Qt6 未找到，CMake 会直接报“未知的语法错误”，因为该命令未被定义。这一点和直接使用add_executable不同，后者是 CMake 内置命令。如果你希望工程更通用（比如以后不用 Qt），也可以继续用add_executable，并手动设置 AUTOMOC。但就 Qt6 项目而言，我建议无脑用qt_add_executable，遵循官方习惯，省心。

4.5 target_link_libraries 的 PUBLIC / PRIVATE

最后一行把 Qt6 的 Widgets 模块链接到可执行目标上：

target_link_libraries(MyFirstQtApp PRIVATE Qt6::Widgets)

引用的是Qt6::Widgets，这就是 CMake 的 target 命名空间。前面find_package找到 Qt6 之后，CMake 会导入一系列带命名空间的库目标，每个模块大概长这样：Qt6::Core、Qt6::Gui、Qt6::Widgets、Qt6::Network。链接时只需写出属于本文件依赖的部分，剩下由 Qt 的 CMake 配置自动传递。

PRIVATE表示Qt6::Widgets只用于链接这个目标，而不会传递给依赖这个目标的上层目标。不管你的工程现在是单机程序还是会被别的目标引用，使用PRIVATE都是最稳妥的起点。如果未来要写共享库并让使用方自动链接 Qt，就再考虑PUBLIC。这里不写Qt6::Core是因为 Widgets 内部已依赖 Core 和 Gui，CMake 会通过传递关系把它们都带上，我们显式写 Widgets 就够了。这也是新手常见的疑惑点：明明编译报错找不到 QString，头文件却明明引用了 QtCore，这是什么原因？大概率是陷在只链接了部分模块的怪圈里。先跑最小工程时，Qt6::Widgets就是那个能带全部依赖的入口。

我附上一个更精细的 CMakeLists.txt，包含最终注释版本，方便直接抄：

cmake_minimum_required(VERSION 3.22) project(MyFirstQtApp VERSION 1.0 LANGUAGES CXX) # 定位 Qt6 并加载所需模块 find_package(Qt6 REQUIRED COMPONENTS Widgets) # Qt6 推荐的工程级配置：开启 moc/uic/rcc 自动处理等 qt_standard_project_setup() # 生成可执行文件目标 qt_add_executable(MyFirstQtApp src/main.cpp ) # 将 Qt6 Widgets 模块链接进来 target_link_libraries(MyFirstQtApp PRIVATE Qt6::Widgets)

5. 从命令行到 IDE 的完整构建流程

5.1 Windows 命令行构建（MinGW 与 MSVC 两种姿势）

第一步是配置工程。打开终端，进入工程根目录，执行：

cmake -S . -B build

-S .表示源码目录是当前目录，-B build表示构建目录是当前目录下的 build 文件夹。这条命令会自动检测系统里的编译器。如果一切正常，它会在 build 目录下生成构建脚本，并打印出类似Build files have been written的提示。

但 Windows 上往往没这么顺利。最常见的问题在于 CMAKE_PREFIX_PATH 没有指向 Qt6 安装目录。如果你安装 Qt6 到了D:/Qt/6.8.0/msvc2022_64，编译器的搜索路径中不包含 Qt，那么引入 find_package 时会报错。因此更可靠的命令行是：

cmake -S . -B build -DCMAKE_PREFIX_PATH=D:/Qt/6.8.0/msvc2022_64

也可以直接用 Qt 安装目录下的Qt 6.8.0配套命令提示符，那个环境里往往已经把 CMake、Ninja 和编译路径都配好了，直接跳到配置步骤。这里我强调一个经验：用-DCMAKE_PREFIX_PATH把 Qt 路径指给 CMake，比把 Qt 的 bin 目录塞进 PATH 然后期待find_package能靠默认路径找到要稳得多。

配置完成后再执行：

cmake --build build

这条命令会读取 build 目录里的配置，调用相应的编译器完成编译。如果你是单配置生成器（Ninja 或 MinGW Makefiles），直接构建的就是你在 configure 时指定的类型，默认多半是 Debug。如果要构建 Release，可以用：

cmake --build build --config Release

注意：如果你用 Visual Studio 生成器且没有指定--config Release，则默认构建 Debug。初次上手建议统一用 Ninja，它会比较快并且配合 CMake 的生成器很成熟。

5.2 在 Qt Creator 中打开与配置 Kit

如果你不想用命令行，Qt Creator 提供了非常顺滑的 CMake 支持。打开 Qt Creator，选择打开项目，选中工程根目录的CMakeLists.txt即可。

Qt Creator 会自动识别 CMake 工程，并弹出“配置项目”或 Kit 选择面板。你需要选一个合适的 Kit，它一般关联着特定的编译器、CMake 和 Qt 版本。如果之前安装 Qt 时是通过在线安装器装的，Qt Creator 通常会自动探测到 Qt 路径。若没有自动识别，要手动在 Kit 设置里指定 Qt 版本的安装目录。

选好 Kit 之后，Qt Creator 会为你自动执行 configure，你只需要点击左下角的绿色运行按钮。它的默认构建配置里有 Debug 和 Release 两种模式，构建目录默认是build-工程名-xxx这样的独立目录。我在用 Qt Creator 时最喜欢的一点是，它生成的 cmake 命令可视化了很多：右键项目可以看到详情信息，还能源代码里看到上下文相关的 Qt 符号解析。对于初学者，能在图形界面里直接断点调试是很有效的学习路径。

5.3 运行验证与第一个窗口

构建完成后，在项目目录下找生成的MyFirstQtApp.exe（Windows）或MyFirstQtApp（Linux/macOS）。命令行方式下，Windows 用户通常在build/（Ninja 单配置）下。如果直接双击这个 exe，很可能会报“找不到 Qt6Widgets.dll”，这是正常的，因为 exe 启动时需要找到 Qt 的动态库。最简单的运行方法是：打开 Qt 安装目录下对应编译器和版本的 bin 文件夹，把Qt6Widgets.dll、Qt6Gui.dll、Qt6Core.dll复制到 exe 的同级目录，这是最笨但最有效的方式。

更好的做法是使用官方提供的部署工具windeployqt。在 Qt 的 bin 目录下执行：

windeployqt build/MyFirstQtApp.exe

它会自动分析 exe 依赖并复制所需的库文件到同级目录，处理完再双击 exe 就能跑起来。如果是从 Qt Creator 运行，Qt Creator 会把必要的 qml 和 dll 路径处理妥当，直接无碍。

当窗口Hello, Qt6 and CMake!出现时，恭喜，你的第一个 CMake Qt6 工程已经彻底跑通。此时你会发现构建系统已经帮我们完成了moc、uic或rcc的调度，程序的构建链路是完整且闭环的。

6. 常见问题排查与经验速查

6.1 找不到 Qt6：CMAKE_PREFIX_PATH 没指对

这个错误在第一次 configure 时几乎人手一个。执行cmake -S . -B build后报：

CMake Error at CMakeLists.txt:5 (find_package): Could not find a package configuration file named "Qt6" with any of...

意思是在默认路径里没有检索到 Qt6Config.cmake。解决办法就一个：把 Qt6 安装路径告诉 CMake。

cmake -S . -B build -DCMAKE_PREFIX_PATH=D:/Qt/6.8.0/msvc2022_64

如果你用的目录是C:/Qt/Qt6.8.0/6.8.0/mingw_64，就按实际路径填。注意CMAKE_PREFIX_PATH指向的是 Qt 安装根目录，它能在该目录的lib/cmake下找到 Qt6 的配置文件。给这个路径时别带lib/cmake后缀，很多新手会把它手动拼成.../lib/cmake，结果导致反而找不到。

另一个常见场景是 Qt Creator 选了 Kit 但报同样的错，那就要去检查 Kit 配置里是否设置了 Qt 版本路径，或者在 Tools > Options > Kits 里重新指定。如果多个版本的 Qt 并存，尤其容易遇到一个项目使用了旧版本 Qt 导致找不到新组件的情况。建议保持不同 Qt 版本之间的CMAKE_PREFIX_PATH隔离。

6.2 Q_OBJECT 相关编译错误：moc 没有正确处理

如果你写了一个带Q_OBJECT宏的自定义类，但没有正确启用 AUTOMOC，或者手动写了add_executable而忘记设置CMAKE_AUTOMOC ON，那么编译到链接阶段时，很可能会报：

undefined reference to vtable for MyClass

或者moc相关文件缺失。这正是我前面强调qt_standard_project_setup()的原因。它不只是为了“规范”，而是在 Qt6 工程里压实了 AUTOMOC 的开启动作。如果你使用的是qt_standard_project_setup()但问题依旧，请检查你的头文件路径是否被 CMake 正确纳入目标源文件列表。尤其是带了自定义类定义和实现的工程，需要把.h文件也写到qt_add_executable的源文件列表里，因为 moc 需要看到包含Q_OBJECT的头文件。例如：

qt_add_executable(MyFirstQtApp src/main.cpp src/myclass.h src/myclass.cpp )

如果漏了.h，CMake 可能不会为这个自定义类生成 moc 输出，就会出现诡异的符号错误。很多网友把时间花在重新安装 Qt 上，实际上一般就是这里漏了。

6.3 源码中文乱码与编码问题

Qt6 默认要求源文件采用 UTF-8 编码。如果你在 Windows 上使用 MSVC 并且源码文件是本地的 GBK 或 GB2312，那么字符串常量可能会出现乱码，甚至编译警告。我在第一个 Qt6 工程里就遇到过：用 Windows 记事本默认保存的源文件，在编译后界面上的中文变成了一堆问号。

解决思路很直接：把源文件改成 UTF-8 编码。在 Qt Creator 里，可以通过右下角的编码按钮切换；在 VS Code 里，可以重新保存并选择 UTF-8。对于 MSVC，老方法是用/utf-8编译选项，而 Qt6 的qt_standard_project_setup()其实已经做了很多编码上的处理，这样反而更推荐始终用 UTF-8 源文件，避免依赖特定的编译选项。如果项目里难免有非 UTF-8 文件，也可以单独设置：

set_source_files_properties(legacy.cpp PROPERTIES COMPILE_OPTIONS "/utf-8")

但这属于权宜之计。从我的实践看，尽早把所有源码统一为 UTF-8 是无痛的，省下的是一次次乱码排查时间。

6.4 Debug 版运行缺 DLL：部署策略别搞混

命令行构建完成后，如果你直接双击build/MyFirstQtApp.exe，极大概率弹出“缺少 Qt6Widgets.dll”。很多人第一反应是自己 Qt 装得不对，其实不是，这纯粹是动态库搜索路径没设置。

在你用 Qt Creator 运行 demo 时，它会在 run 配置里自动把 Qt 的 bin 目录设为 PATH，所以一切正常。当你手工运行时，就需要自己处理 DLL 的部署。最快的验证方式是临时在终端设置变量（Windows 上以 PowerShell 为例）：

$env:PATH = "D:/Qt/6.8.0/msvc2022_64/bin;$env:PATH" .\build\MyFirstQtApp.exe

这样运行后窗口出现，说明程序没问题，只是部署问题。接着用windeployqt把 dll 复制到 exe 旁边，之后即使不设置环境变量也能直接运行系统。

我踩过最尴尬的坑是：一个是 Debug 版 exe，一个是 Release 版 Qt 库，两者混在一起会报Mismatch Detected for Qt之类的运行错误。所以部署时要注意 Qt 的 debug/release 形式，比如Qt6Widgetsd.dll带字母 d 的是 debug 版。windeployqt会根据你的 exe 是 debug 还是 release 自动选择，但如果你手动复制 dll，很容易复制错了。

6.5 其他高频小坑汇总

顺手整理几个我见过很多次的问题，做成速查表：

这里想额外强调一点：不是所有报错都来自 CMake。我第一次用 CMake 跑 Qt 工程时，花了一下午调 configure，最后发现是杀毒软件把生成的临时文件隔离了。所以如果遇到奇怪的现象，可以先用cmake --build build --verbose看真实输出，再判断是哪个环节。

最后再分享一个我个人的习惯：每次跑通一个小工程，我会把它作为后续所有 Qt 项目的起点模板。当需要创建新项目时，复制整个干净目录，改一下project()里的名字，再增加源文件即可。这个流程比每次从空工程开始要稳得多，尤其是当你已经为某个 CMakeLists.txt 调整好所有路径和依赖时，它就成了你的武器库。下一步，你可以在这个基础上试加一个 Qt Quick 窗口、引入 QML 模块，或者把第三方库用 CMake 的FetchContent抓进来。工程越复杂，你会发现 CMake 的结构化管理越能帮你兜住底。