第 1.2 节

Windows开发环境搭建与测试

作者

董佳辉

发布于 2026/10/27更新于 2026/10/27

这一章先不改代码，只做一件很具体的事：

在 Windows 上把我准备好的 CMake 模板跑起来。

我们继续使用 GCC、CMake、Ninja 和 VSCode。准备好环境后，后面的 C++ 代码和 Linux 章节共用，不需要再学一套语法。如果你用的是 Linux，请看 Linux开发环境搭建与测试。

本章最终效果

这一章会按下面的顺序来：

安装 MSYS2，用它准备 GCC、CMake、Ninja、GDB 和 Eigen。
配置 Windows 的 PATH，检查这些工具能否正常运行。
下载模板，选择 windows-debug，先原样运行。
用 VSCode 构建、运行和调试模板程序。
确认以后在哪里写代码、在哪里重新构建。

本节按 Windows 10 / 11 的 64 位环境讲解。工具的安装窗口和版本号可能会变化，重点看工具名称、安装路径和命令输出。

为何采用 MSYS2

在 Windows 上分别下载、解压和配置开发工具，需要处理多个安装目录和环境变量。MSYS2 可以通过包管理器统一安装和更新工具，提供接近 Linux 的配置体验，因此本教程采用 MSYS2 UCRT64。

先认识 MSYS2 和 UCRT64

MSYS2 是 Windows 上的一套开发工具和软件包管理环境。我们用它安装编译器和依赖，类似 Linux 用 apt 或 dnf 安装软件。

UCRT64 是 MSYS2 提供的一种环境，使用 GCC，面向 64 位 Windows，并采用微软的 UCRT。这里统一选择它，安装的软件包也都使用 mingw-w64-ucrt-x86_64- 前缀。

名字	本章里负责什么
MSYS2	安装、更新开发工具和库
UCRT64	本章使用的 64 位 Windows GCC 环境
`pacman`	MSYS2 的软件包管理命令
`gcc` / `g++`	编译 C / C++ 代码
CMake / Ninja	配置工程、执行构建
GDB	下断点、查看变量、单步运行

这些工具生成的是原生 Windows 可执行程序。模板本身没有写死 MSYS2 路径，也可以使用独立安装的 MinGW-w64 工具链。

环境区别见 MSYS2 官方说明，VSCode 的 Windows GCC 教程也使用这条安装路线。

安装基础工具

安装 MSYS2

打开 MSYS2 官网，下载并运行安装程序。

下面统一假设安装到：

C:\msys64

如果你安装到了其他位置，后面出现的路径也要对应修改。

安装完成后，从开始菜单打开 MSYS2 UCRT64 终端，先更新：

pacman -Syu

如果更新程序提示关闭终端，就按提示关闭，再重新打开 UCRT64 终端，再运行一次更新命令。更新完成后再继续安装工具。

安装编译器、构建工具和依赖

仍然在 UCRT64 终端中执行（这就是类似Linux的安装环境的命令）：

pacman -S --needed \
  mingw-w64-ucrt-x86_64-git \
  mingw-w64-ucrt-x86_64-gcc \
  mingw-w64-ucrt-x86_64-cmake \
  mingw-w64-ucrt-x86_64-ninja \
  mingw-w64-ucrt-x86_64-gdb \
  mingw-w64-ucrt-x86_64-eigen3

出现确认提示时，确认安装即可。

其中 eigen3 是模板原始示例用到的库。这里使用的是软件包名称，实际库版本以仓库当前提供的版本为准；在 CMake 中仍然使用 Eigen3::Eigen 这个目标。

注意：本节的软件包都来自 UCRT64 环境。不要把 /usr/bin 中面向 MSYS 环境的编译器当成这里的 Windows MinGW-w64 编译器。

配置 PATH

安装完工具后，需要让 PowerShell 和 VSCode 能找到它们。

默认安装位置对应的工具目录是：

C:\msys64\ucrt64\bin

在 Windows 开始菜单搜索“编辑账户的环境变量”，打开后：

找到用户变量中的 Path。
点击编辑，再点击新建。
添加上面的 C:\msys64\ucrt64\bin。
保存后，关闭已经打开的 PowerShell 和 VSCode，再重新打开。

注意：是在原来的 Path 中增加一项，不是把原来的内容全部替换掉。

检查工具是否安装成功

下面开始，除非专门标明 UCRT64 终端，否则 Windows 命令都在 PowerShell 中执行。

git --version
cmake --version
ninja --version
g++ --version
gdb --version

这些命令都能输出版本号，说明基础工具已经能被找到。 CMake 要求 3.22 或更新版本，编译器需要支持 C++20。

如果电脑上曾经安装过其他编译器，再检查实际调用的是哪一个：

where.exe gcc
where.exe g++
where.exe cmake
where.exe ninja
g++ -dumpmachine

按照本节安装时，前几项路径应指向 C:\msys64\ucrt64\bin，-dumpmachine 通常会输出：

x86_64-w64-mingw32

这里的目标名称并不表示只能生成 32 位程序，前面的 x86_64 才说明本节使用的是 64 位目标。

安装和配置 VSCode

从 VSCode 官网下载 Windows 安装程序并安装。需要从命令行使用 code . 时，在安装选项中启用添加到 PATH；安装完成后重新打开终端。

打开 VSCode 后，可以像 Linux 章节一样，为 C++ 单独建立一个配置文件。扩展主要安装：

CMake Tools。
C/C++，用于 GDB 调试。
C/C++ DevTools，按需要使用。
clangd，用于代码提示、跳转和诊断。

先跑通 CMake 构建和调试，再配置 clangd。代码能编译与编辑器有没有正确提示，是两件需要分别检查的事。

clone CMake 模板

在准备放工程的目录中打开 PowerShell：

git clone https://github.com/tungchiahui/CMake_Template.git hello_cpp
cd hello_cpp
code .

hello_cpp 是项目文件夹名，模板当前的程序名仍然是 cmake_template。

后面的命令都在这个工程根目录执行。先不要修改 CMake 文件，也不要急着把示例库删掉，先确认原始工程能运行。

先原样跑通模板

用命令行方式运行

在 VSCode 中打开 PowerShell 终端，执行：

cmake --preset windows-debug
cmake --build --preset windows-debug
./build/windows-debug/bin/cmake_template.exe

输出应类似：

[lib1] Vector v = 1 2 3
[lib1] Norm = 3.74166
[lib2] Matrix m =
1 2
3 4
[lib2] Determinant = -2

说明 GCC、CMake、Ninja、Eigen 和模板中的两个动态库已经能够一起工作。

Windows 中构建出的程序位于：

build/windows-debug/bin/cmake_template.exe

Windows 预设会把两个示例库静态链接到主程序中。写练习时继续使用普通函数声明，按前面的命令重新构建、运行即可。

原样模板还带有一个运行检查，可以执行：

ctest --preset windows-debug

后面的练习会修改 main.cpp，输出也会改变。这个测试检查的是原始 Eigen 示例，不是所有练习的统一判题器；开始改示例后，日常使用 Build 和 Launch 即可。

用 VSCode 图形化方式运行

打开左侧 CMake 面板，按照下面的顺序操作：

选择 Windows GCC Debug，对应的 preset 名是 windows-debug。
点击 Configure，等待配置完成。
点击 Build。
选择 cmake_template 作为运行或调试的 target。
点击 Launch，观察终端中的示例输出。

这些操作分别对应刚才的 configure、build 和运行命令。以后改完代码后，通常只需要再次 Build，再 Launch。

下断点并调试

打开 src/main.cpp，在调用 lib1::run_eigen_vector_example() 的行号旁单击，添加一个断点。

确认仍然选择 Debug 预设和 cmake_template target，然后点击 CMake Tools 的 Debug 按钮。程序停在断点处后，可以查看调用栈、变量并单步进入函数。

如果提示找不到调试器，先在 PowerShell 中确认 gdb --version 能运行。默认安装位置的 GDB 为：

C:/msys64/ucrt64/bin/gdb.exe

可以在 VSCode 的 CMake Tools 调试设置中指定：

{
  "cmake.debugConfig": {
    "MIMode": "gdb",
    "miDebuggerPath": "C:/msys64/ucrt64/bin/gdb.exe"
  }
}

想用 F5 执行同样的操作时，打开 VSCode 键盘快捷方式，搜索 CMake: Debug 并绑定 F5。这样会调试当前 CMake target，无需手写 launch.json。

配置 clangd

在 UCRT64 终端安装 clangd 程序：

pacman -S --needed mingw-w64-ucrt-x86_64-clang-tools-extra

安装 VSCode 的 clangd 扩展后，在项目根目录把 .clangd 中的数据库路径改为：

CompileFlags:
  CompilationDatabase: build/windows-debug

先执行一次 Configure，让 build/windows-debug/compile_commands.json 生成出来。

如果扩展找不到 clangd 程序，或者标准库头文件仍然报错，可以在 VSCode 的本地设置中使用：

{
  "clangd.path": "C:/msys64/ucrt64/bin/clangd.exe",
  "clangd.arguments": [
    "--query-driver=C:/msys64/ucrt64/bin/g++.exe,C:/msys64/ucrt64/bin/gcc.exe"
  ],
  "C_Cpp.intelliSenseEngine": "disabled"
}

--query-driver 允许 clangd 向这里指定的编译器查询标准库头文件位置。路径要对应自己安装的编译器。详细原理见 clangd 系统头文件说明。

最后在命令面板执行 clangd: Restart language server。关闭 C/C++ 的 IntelliSense 不会关闭它提供的 GDB 调试功能。

验证安装结果

日常写代码直接运行 build 目录里的程序。只有准备分发或检查安装布局时，再执行：

cmake --install build/windows-debug
./install/windows-debug/bin/cmake_template.exe

安装时，模板还会准备工具链中找到的常用 GCC 运行库。保持安装目录的内部结构，整体复制到其他位置后再运行。以后新增第三方库时，还要检查相应依赖的安装要求。

使用已经单独安装好的工具

如果电脑上已经有支持 C++20 的 MinGW-w64 GCC、CMake 3.22+、Ninja 和 GDB，也可以继续使用，不必更换安装方式。

把它们各自的 bin/ 加入 PATH，再按前面的版本检查、configure 和 build 步骤执行即可。

Eigen 是头文件库，不需要分别编译 GCC 版和 MSVC 版。对于当前模板的 find_package(Eigen3 REQUIRED)，还需要安装目录提供 Eigen3Config.cmake。

例如 Eigen 安装在 C:/deps/eigen，可以临时设置安装前缀：

$env:CMAKE_PREFIX_PATH = "C:/deps/eigen"
cmake --preset windows-debug

或者直接指定配置文件所在的目录：

cmake --preset windows-debug -DEigen3_DIR="C:/deps/eigen/share/eigen3/cmake"

上面的路径要对应实际文件位置。单纯解压 Eigen 源码可以获得头文件，但不一定已经有生成好的 CMake 配置文件；使用安装包或先执行 Eigen 的 CMake 安装步骤，更适合当前模板的查找方式。参见 Eigen 官方 CMake 说明。

常见问题

找不到 gcc、Ninja 或 GDB

先检查对应的软件包是否装好，再用 where.exe 检查 PATH。修改系统环境变量后，需要重新打开 VSCode，它不会自动获得已经打开之后才修改的 PATH。

看不到 windows-debug

确认打开的是项目根目录，里面包含 CMakePresets.json。模板按当前系统显示 configure preset；Windows 使用 Windows 原生 CMake 执行时，应看到 Windows 两组预设。

程序启动失败

先确认运行的是 build/windows-debug/bin/cmake_template.exe，并且开发环境的 GCC 工具目录位于 PATH 中。

测试安装结果时，重新执行 install，再运行安装目录中的 EXE，不要只把 EXE 从目录中单独拿出来。

切换编译器后构建异常

一个构建目录会缓存之前选择的编译器。更换工具链后，在 PowerShell 中清理对应的构建目录，再重新配置：

Remove-Item -Recurse -Force build/windows-debug
cmake --preset windows-debug
cmake --build --preset windows-debug

只有目录存在时才执行删除命令，删除前确认路径是项目的构建目录。这里不要求使用 cmake --fresh，这样也兼容模板最低要求的 CMake 3.22。

中文显示乱码

先将源文件保存为 UTF-8，并使用支持 UTF-8 的终端。PowerShell 终端中的编码设置与源文件编码是两件事；需要时可以在当前终端执行 chcp 65001 后重新运行。涉及文件内容时，文件本身的编码也要一致。

下一步学什么

环境跑通后，进入 C++基础初识。前期只修改 src/main.cpp，继续使用本节的 Windows 构建和运行方式。

等学到函数分文件编写、第三方库和工程组织时，再回来看 CMake工程模板。