VSCode+Qt+CMake详细地讲解

个人博客：blogs.wurp.top

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

1. 安装 VSCode

访问 VSCode 官网下载并安装。
安装完成后，打开 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

访问 Qt 官网下载 Qt Online Installer。
运行安装程序，登录或注册 Qt 账户。
在选择组件页面，至关重要的一步：
- 选择最新的 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

访问 CMake 官网下载安装包。
安装时，务必勾选 "Add CMake to the system PATH for all users"，这样 VSCode 和终端才能找到它。
安装完成后，打开终端 (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 的库和工具。

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

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

json 复制代码

{
    "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 复制代码

# 指定 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.cpp
    MainWindow.h
    MainWindow.cpp
    # MainWindow.ui  # 如果启用了 AUTOUIC，通常不需要直接添加 .ui 文件
    # resources.qrc  # 如果启用了 AUTORCC，通常不需要直接添加 .qrc 文件
)

# 将找到的 Qt 库链接到你的可执行文件
target_link_libraries(${PROJECT_NAME} PRIVATE
    Qt6::Core
    Qt6::Gui
    Qt6::Widgets
)

# 在 Windows 上，如果是 GUI 应用程序（非控制台），添加以下代码
if (WIN32)
    win32_gui_executable(${PROJECT_NAME})
endif()

3. 编写简单的源代码

main.cpp

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

cpp 复制代码

#pragma once

#include <QMainWindow>

class MainWindow : public QMainWindow
{
    Q_OBJECT // 必须的宏，用于支持 Qt 的信号/槽机制

public:
    MainWindow(QWidget *parent = nullptr);
    ~MainWindow();
};

MainWindow.cpp

cpp 复制代码

#include "MainWindow.h"

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

MainWindow::~MainWindow() {}

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

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

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

CMake 找不到 Qt？
- 检查 settings.json 中的 qtDir 路径是否正确。
- 尝试在 CMakeLists.txt 中手动设置 set(Qt6_DIR "你的Qt安装路径/lib/cmake/Qt6")。
构建失败，提示找不到 moc_MainWindow.cpp 之类的文件？
- 确保 CMakeLists.txt 中设置了 set(CMAKE_AUTOMOC ON)。
- 确保你的头文件包含了 Q_OBJECT 宏。
- 尝试执行 CMake: Delete Cache and Reconfigure 命令，然后重新构建。
如何添加 .ui 文件或 .qrc 文件？
- 将 .ui 文件放在源码目录。
- 在 CMakeLists.txt 的 add_executable 命令中不需要 直接添加 .ui 文件。AUTOUIC 会自动处理。
- 确保 .ui 文件对应的头文件（如 MainWindow.h）中包含了使用 ui->setupUi(this); 的代码。.qrc 资源文件同理。
如何清理构建？
- 直接删除项目根目录下的 build 文件夹，然后重新 Configure 和 Build。

总结

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

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

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