VSCode+Qt+CMake详细地讲解

个人博客：blogs.wurp.top

第一部分：环境准备与安装

1. 安装 VSCode

1. 访问 VSCode 官网 下载并安装。
2. 安装完成后，打开 VSCode，安装以下必备扩展：
   • C/C++ (Microsoft): 提供 C/C++ 语言的 IntelliSense、调试等功能。
   • CMake (Microsoft): 提供 CMake 项目的构建、调试、配置支持。
   • CMake Tools (Microsoft): CMake 扩展的增强工具，是核心。
   • (可选) Qt Configure (TheQtCompany): 帮助配置 Qt 环境，提供 .ui 文件预览等功能。
   • (可选) Qt Tools (TheQtCompany): 提供 Qt 特有的语法高亮等。

2. 安装 Qt

1. 访问 Qt 官网 下载 Qt Online Installer。

2. 运行安装程序，登录或注册 Qt 账户。

3. 在选择组件页面，至关重要的一步：

   • 选择最新的 Qt 版本 (如 Qt 6.7.0)。
   • 展开该版本，勾选以下组件：
     • MSVC 2019 64-bit (如果你在 Windows 上使用 Visual Studio 的编译器) 或
     • MinGW 11.2.0 64-bit (如果你使用 MinGW 编译器) 或
     • Android, iOS, macOS 等 (根据你的目标平台选择)。
   • 务必勾选 Sources 和 Debugging Tools for Windows (Windows MSVC 下)，这对调试非常有帮助。
   • 勾选 Qt Creator（虽然我们用 VSCode，但 Qt Creator 自带了许多有用的工具，如 qmake, uic, moc 等，这些工具在构建时是必需的）。

   建议： 如果你使用 MSVC，请确保系统已安装对应版本的 Visual Studio Build Tools 或 Visual Studio。

3. 安装 CMake

1. 访问 CMake 官网 下载安装包。
2. 安装时，务必勾选 “Add CMake to the system PATH for all users”，这样 VSCode 和终端才能找到它。
3. 安装完成后，打开终端 (CMD/PowerShell)，输入 cmake --version 验证是否安装成功。

4. 安装编译器 (如果未安装)

• Windows (MSVC): 安装 Visual Studio 并勾选 “C++ 桌面开发” 工作负载。
• Windows (MinGW): 可以单独安装 MinGW-w64，但更简单的方法是如上所述，在安装 Qt 时直接勾选 MinGW 组件。
• Linux: 通常系统自带 GCC/G++，可通过包管理器安装 (sudo apt install build-essential on Ubuntu)。
• macOS: 安装 Xcode Command Line Tools (xcode-select --install)。

---

第二部分：配置 VSCode 环境

1. 配置 Qt 路径

VSCode 需要知道 Qt 的安装位置，以便 CMake Tools 扩展能找到 Qt 的库和工具。

1. 打开 VSCode 的设置 (Ctrl+,)。
2. 搜索 cmake kit。
3. 找到 Cmake: Kits 设置，点击 “在 settings.json 中编辑”。
4. 这会打开 settings.json 文件。我们需要添加一个 “Kit”。

示例配置 (请根据你的实际路径修改):

{"cmake.configureOnOpen": false, // 可选：建议关闭，手动配置"cmake.generator": "Ninja",     // 可选：推荐使用更快的 Ninja 代替 NMake"cmake.kits": [{"name": "Qt-6.7.0-MSVC2019_64","compilers": {"C": "C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.29.30133/bin/Hostx64/x64/cl.exe","CXX": "C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.29.30133/bin/Hostx64/x64/cl.exe"},"environmentVariables": {// 将 Qt 的 bin 目录和编译器的目录添加到 PATH"PATH": "C:/Qt/6.7.0/msvc2019_64/bin;C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.29.30133/bin/Hostx64/x64;${env:PATH}"},"qtDir": "C:/Qt/6.7.0/msvc2019_64" // 最关键的一行，指向你的 Qt 安装目录}]
}

• name: 给你的配置起一个易懂的名字。
• compilers: 指定 C 和 C++ 编译器的完整路径。
• environmentVariables: 设置临时的 PATH 环境变量，确保构建时能找到 moc, uic, rcc 等 Qt 工具以及编译器。
• qtDir: CMake Tools 扩展用这个变量来查找 Qt。

更简单的方法：
很多时候，CMake Tools 会自动扫描系统并生成 Kits。安装完上述软件后，重启 VSCode，点击底部状态栏的 “No Kit Selected” 或已选择的 Kit 名称，可能会自动弹出检测到的 Kits 列表（包括上面配置的），直接选择即可。

---

第三部分：创建并配置一个 CMake Qt 项目

1. 项目结构

创建一个新的项目文件夹，结构如下：

my_qt_app/
├── CMakeLists.txt
├── main.cpp
├── MainWindow.cpp
├── MainWindow.h
├── MainWindow.ui (可选，UI文件)
└── resources.qrc (可选，资源文件)

2. 编写 CMakeLists.txt

这是 CMake 构建系统的核心配置文件。

# 指定 CMake 的最低版本要求。Qt6 推荐使用 3.16 或更高版本。
cmake_minimum_required(VERSION 3.16)# 设置项目名称和版本
project(MyQtApp VERSION 1.0.0 LANGUAGES CXX)# 设置 C++ 标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)# 自动调用 MOC、UIC、RCC
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTOUIC ON)
set(CMAKE_AUTORCC ON)# 查找所需的 Qt 组件
# 这里的 Core Gui Widgets 是你的项目所依赖的 Qt 模块
find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets)# 如果你的 Qt 安装在非标准路径，可能需要手动设置 Qt6_DIR
# set(Qt6_DIR "C:/Qt/6.7.0/msvc2019_64/lib/cmake/Qt6")# 添加可执行文件目标
add_executable(${PROJECT_NAME}main.cppMainWindow.hMainWindow.cpp# MainWindow.ui  # 如果启用了 AUTOUIC，通常不需要直接添加 .ui 文件# resources.qrc  # 如果启用了 AUTORCC，通常不需要直接添加 .qrc 文件
)# 将找到的 Qt 库链接到你的可执行文件
target_link_libraries(${PROJECT_NAME} PRIVATEQt6::CoreQt6::GuiQt6::Widgets
)# 在 Windows 上，如果是 GUI 应用程序（非控制台），添加以下代码
if (WIN32)win32_gui_executable(${PROJECT_NAME})
endif()

3. 编写简单的源代码

main.cpp

#include <QApplication>
#include "MainWindow.h"int main(int argc, char *argv[])
{QApplication a(argc, argv);MainWindow w;w.show();return a.exec();
}

MainWindow.h

#pragma once#include <QMainWindow>class MainWindow : public QMainWindow
{Q_OBJECT // 必须的宏，用于支持 Qt 的信号/槽机制public:MainWindow(QWidget *parent = nullptr);~MainWindow();
};

MainWindow.cpp

#include "MainWindow.h"MainWindow::MainWindow(QWidget *parent): QMainWindow(parent)
{// 设置窗口标题和大小setWindowTitle("My First Qt App in VSCode");resize(800, 600);
}MainWindow::~MainWindow() {}

---

第四部分：在 VSCode 中构建和运行

1. 打开项目文件夹: 用 VSCode 打开 my_qt_app 文件夹。
2. 选择 Kit: 点击底部状态栏的 “No Kit Selected”，从列表中选择你之前配置好的 Kit (如 Qt-6.7.0-MSVC2019_64)。
3. 选择 Variant (构建类型): 点击底部状态栏的 “[Debug]”，可以选择 Debug, Release, RelWithDebInfo等。
4. 配置项目 (Configure):
   • 按下 Ctrl+Shift+P 打开命令面板。
   • 输入 CMake: Configure 并执行。或者点击底部状态栏的 “Configure” 按钮。
   • 这会让 CMake 读取你的 CMakeLists.txt，检查依赖，并在项目根目录生成一个 build 文件夹（默认）和 CMakeCache.txt。
5. 构建项目 (Build):
   • 按下 Ctrl+Shift+P，输入 CMake: Build 并执行。或者点击底部状态栏的 “Build” 按钮 (一个小齿轮)。
   • 编译输出会显示在终端中。成功后，可在 build/Debug 或 build/Release 文件夹中找到生成的 .exe 文件。
6. 运行项目 (Run):
   • 按下 Ctrl+Shift+P，输入 CMake: Run Without Debugging。或者点击底部状态栏的 “Play” 按钮。
   • 你的 Qt 应用程序就会启动！
7. 调试 (Debug):
   • 首先在代码中设置断点 (点击行号左侧)。
   • 然后点击底部状态栏的 “Debug” 按钮 (一个带虫子的播放按钮) 或按 F5。
   • VSCode 会启动程序并在断点处暂停，你可以查看变量、调用堆栈等信息。

---

第五部分：常见问题与技巧 (FAQ)

1. CMake 找不到 Qt？

   • 检查 settings.json 中的 qtDir 路径是否正确。
   • 尝试在 CMakeLists.txt 中手动设置 set(Qt6_DIR “你的Qt安装路径/lib/cmake/Qt6”)。

2. 构建失败，提示找不到 moc_MainWindow.cpp 之类的文件？

   • 确保 CMakeLists.txt 中设置了 set(CMAKE_AUTOMOC ON)。
   • 确保你的头文件包含了 Q_OBJECT 宏。
   • 尝试执行 CMake: Delete Cache and Reconfigure 命令，然后重新构建。

3. 如何添加 .ui 文件或 .qrc 文件？

   • 将 .ui 文件放在源码目录。
   • 在 CMakeLists.txt 的 add_executable 命令中不需要直接添加 .ui 文件。AUTOUIC 会自动处理。
   • 确保 .ui 文件对应的头文件（如 MainWindow.h）中包含了使用 ui->setupUi(this); 的代码。.qrc 资源文件同理。

4. 如何清理构建？

   • 直接删除项目根目录下的 build 文件夹，然后重新 Configure 和 Build。

总结

VSCode + Qt + CMake 的组合提供了高度可定制化和现代化的开发体验。虽然初始配置比 Qt Creator 稍显复杂，但它提供了无与伦比的编辑器体验、强大的扩展生态系统和对构建流程的更深层次控制。一旦配置完成，其流畅的开发体验会让你觉得物有所值。

这套组合是当前 Qt C++ 开发的主流选择之一，它结合了：

• VSCode: 轻量级、插件丰富、生态强大的代码编辑器。
• Qt: 强大的跨平台应用开发框架。
• CMake: 跨平台的自动化构建系统，能生成用于编译的 Makefile 或项目文件。