1. 项目概述
作为一名使用Qt超过8年的开发者，我见证了Qt从qmake到CMake的完整迁移过程。今天要分享的是如何从零开始构建一个基于CMake的Qt6项目，这是每个现代Qt开发者都必须掌握的技能。
记得2018年Qt官方首次宣布将CMake作为一等公民支持时，社区里掀起了轩然大波。如今5年过去，CMake已经成为Qt开发的事实标准。但很多从Qt5过渡来的开发者，特别是习惯了qmake的老手，在初次接触CMake时总会遇到各种"水土不服"。
本文将带你完整走一遍创建Qt6 CMake项目的全流程，从环境准备到第一个窗口显示，我会特别标注那些官方文档没写但实际开发中一定会遇到的坑。无论你是刚接触Qt的新手，还是从Qt5迁移来的老鸟，这篇指南都能让你少走弯路。
2. 环境准备与工具链配置
2.1 Qt6安装注意事项
首先需要从Qt官网获取在线安装器。这里有个关键选择：建议安装最新的LTS版本（当前是Qt 6.2.4+），而不是追求最新版本。我在多个项目中使用非LTS版本时都遇到过奇怪的兼容性问题。
安装组件选择时，务必勾选：
- Qt 6.2.4（或你选择的版本）
- Developer and Designer Tools中的CMake和Ninja
- Additional Libraries中的Qt 5 Compatibility Module（方便后续使用一些Qt5的特性）
重要提示：安装路径不要包含中文或空格！这是很多后续编译问题的根源。我习惯安装在C:\Qt（Windows）或/opt/Qt（Linux）这样的纯英文路径。
2.2 构建工具链配置
现代Qt开发推荐使用CMake + Ninja的组合。相比传统的make，Ninja的构建速度更快，特别是在Windows平台上。安装Qt时如果按我上面的建议勾选了相关组件，这些工具应该已经就绪。
验证工具链是否正常工作：
bash复制cmake --version # 需要3.16+
ninja --version # 需要1.8+
qmake -v # 确认是Qt6版本
如果系统中有多个Qt版本，建议通过qtchooser（Linux/macOS）或设置环境变量（Windows）来指定默认使用Qt6。
3. 创建第一个CMake Qt6项目
3.1 项目目录结构规划
规范的目录结构能避免后续很多麻烦。我推荐的基础结构如下：
code复制my_qt_app/
├── CMakeLists.txt # 主构建文件
├── src/ # 源代码目录
│ ├── main.cpp
│ └── mainwindow.cpp
├── include/ # 头文件（可选）
│ └── mainwindow.h
└── resources/ # 资源文件
└── images/
这种结构清晰区分了不同类型文件，特别适合后续项目扩展。相比传统的把所有文件放在根目录下的做法，这种结构在大中型项目中优势明显。
3.2 CMakeLists.txt详解
这是整个项目的核心配置文件。让我们逐部分解析一个最小化的Qt6 CMake配置：
cmake复制cmake_minimum_required(VERSION 3.16)
# 项目定义
project(MyQtApp LANGUAGES CXX)
# 查找Qt库 - 关键设置！
find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets)
# 启用自动处理moc、uic等Qt特性
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)
set(CMAKE_AUTOUIC ON)
# 添加可执行文件
add_executable(my_qt_app
src/main.cpp
src/mainwindow.cpp
include/mainwindow.h
)
# 链接Qt库
target_link_libraries(my_qt_app PRIVATE
Qt6::Core
Qt6::Gui
Qt6::Widgets
)
几个关键点说明：
cmake_minimum_required必须≥3.16，这是Qt6的最低要求find_package要明确列出所有需要的Qt模块- 三个AUTO开关（AUTOMOC/AUTORCC/AUTOUIC）必须开启，否则需要手动处理元对象编译
- 头文件也要加入
add_executable，否则moc可能无法正确工作
3.3 主窗口实现
让我们实现一个最简单的带按钮的窗口。首先是mainwindow.h：
cpp复制#include <QMainWindow>
#include <QPushButton>
class MainWindow : public QMainWindow {
Q_OBJECT // 必须包含这个宏
public:
explicit MainWindow(QWidget *parent = nullptr);
private slots:
void onButtonClicked();
private:
QPushButton *m_button;
};
对应的mainwindow.cpp实现：
cpp复制#include "mainwindow.h"
MainWindow::MainWindow(QWidget *parent)
: QMainWindow(parent) {
m_button = new QPushButton("Click me!", this);
connect(m_button, &QPushButton::clicked,
this, &MainWindow::onButtonClicked);
resize(400, 300);
}
void MainWindow::onButtonClicked() {
m_button->setText("Clicked!");
}
最后是main.cpp：
cpp复制#include "mainwindow.h"
#include <QApplication>
int main(int argc, char *argv[]) {
QApplication app(argc, argv);
MainWindow window;
window.show();
return app.exec();
}
4. 构建与运行
4.1 生成构建系统
在项目根目录下执行：
bash复制mkdir build
cd build
cmake -G Ninja ..
这里有几个常见问题需要注意：
- 如果提示找不到Qt6，可能需要通过
-DCMAKE_PREFIX_PATH=/path/to/Qt6/lib/cmake指定Qt安装路径 - Windows用户可能需要使用
cmake -G "Ninja" ..（带引号） - 首次配置较慢，因为要处理moc等元对象编译
4.2 编译与运行
生成构建系统后，执行：
bash复制ninja
./my_qt_app # 或Windows下的my_qt_app.exe
你应该能看到一个带按钮的窗口。点击按钮后文字会变化，说明信号槽机制工作正常。
5. 常见问题与解决方案
5.1 找不到Qt6的问题
这是新手最常见的问题，症状是CMake报错"Could not find a package configuration file provided by Qt6"。
解决方案：
- 明确设置CMAKE_PREFIX_PATH：
bash复制
cmake -DCMAKE_PREFIX_PATH=/path/to/Qt6/lib/cmake .. - 检查Qt安装目录下的lib/cmake是否确实存在
- 确保没有残留的旧版本Qt环境变量干扰
5.2 元对象编译失败
如果忘记在头文件中添加Q_OBJECT宏，或者moc处理失败，会遇到各种奇怪的链接错误。
典型症状：
- 报错中有"vtable"、"undefined reference"等关键词
- 信号槽无法正常工作
解决方案：
- 确保所有QObject派生类都有Q_OBJECT宏
- 确认CMakeLists.txt中开启了AUTOMOC
- 头文件必须列入add_executable
- 清理build目录重新构建
5.3 资源文件处理
Qt的资源系统（.qrc文件）在CMake中需要特殊处理。假设我们有个resources/images/logo.png，步骤如下：
- 创建resources.qrc：
xml复制<RCC>
<qresource prefix="/">
<file>images/logo.png</file>
</qresource>
</RCC>
- 在CMakeLists.txt中添加：
cmake复制# 添加资源文件
set(RESOURCES resources/resources.qrc)
# 修改add_executable包含资源
add_executable(my_qt_app ...
${RESOURCES}
)
- 代码中使用":/images/logo.png"路径访问资源
6. 高级配置技巧
6.1 模块化项目结构
当项目变大时，建议拆分为多个CMake子项目。例如：
code复制my_qt_app/
├── CMakeLists.txt
├── src/
│ ├── app/ # 主程序
│ ├── core/ # 核心库
│ └── components/ # 可复用组件
└── tests/ # 测试代码
对应的CMakeLists.txt需要：
cmake复制# 定义库
add_library(core STATIC src/core/core.cpp include/core/core.h)
target_link_libraries(core PUBLIC Qt6::Core)
# 主程序链接库
add_executable(my_qt_app src/app/main.cpp)
target_link_libraries(my_qt_app PRIVATE core)
6.2 跨平台处理
Qt的优势之一就是跨平台，但在CMake中需要特别注意平台相关代码：
cmake复制if(WIN32)
# Windows特定设置
target_sources(my_qt_app PRIVATE src/platform/win32.cpp)
elseif(APPLE)
# macOS特定设置
target_link_libraries(my_qt_app PRIVATE "-framework Cocoa")
endif()
6.3 调试技巧
在CMake中启用调试信息：
cmake复制if(CMAKE_BUILD_TYPE STREQUAL "Debug")
target_compile_definitions(my_qt_app PRIVATE QT_DEBUG)
target_compile_options(my_qt_app PRIVATE -g)
endif()
使用QtCreator时，可以在项目设置中直接指定构建类型。命令行用户可以使用：
bash复制cmake -DCMAKE_BUILD_TYPE=Debug ..
7. 从Qt5迁移的注意事项
如果你有现成的Qt5项目想迁移到Qt6+CMake，需要特别注意：
-
头文件变化：
- QtWidgets/QApplication → QtWidgets/qapplication.h
- 其他模块类似，去掉了Qt前缀
-
废弃的特性：
- QRegExp → QRegularExpression
- QDesktopWidget → QScreen
- 旧的图形渲染管线（OpenGL相关）
-
信号槽连接语法：
- 推荐使用新式的函数指针语法
- 旧式字符串语法仍然可用但不够安全
-
属性系统：
- Q_PROPERTY现在需要完全限定类型名
- 枚举值处理更加严格
我在实际迁移过程中发现，大约80%的问题都集中在上述几个方面。建议先创建一个新的CMake项目，然后逐步迁移代码，而不是直接修改原有的.pro文件。