Windows 用 VS Code 配一套能编译、能调试的 C++ 环境

这套配置适合想在 Windows 上写普通 C++ 程序的人：编辑器用 VS Code，编译器用 MSYS2 的 UCRT64 GCC，调试器用同一套工具链里的 GDB。不要把它和 Visual Studio 的 MSVC 混在一起配，路径一乱，后面排错会很烦。

参考链接：

先确认你要装哪一套

Windows 上常见 C++ 环境有两条路：

  • MSVC：安装 Visual Studio Build Tools，走 Microsoft 编译器。
  • MinGW-w64 / GCC：用 MSYS2 安装 GCC，命令和 Linux/macOS 上更接近。

本文选第二条。原因很简单：很多入门教程、OJ、本地小工具都直接给 g++ main.cpp -o main 这种命令，用 GCC 跑起来更直观。

1. 安装 MSYS2

去 MSYS2 官网下载安装包：https://www.msys2.org/

安装路径用默认值最省事：

C:\msys64

不要放到带中文、空格或者云同步目录的位置。不是一定不能用，但出了奇怪路径问题时很难判断是工具链问题还是目录问题。

安装结束后，从开始菜单打开：

MSYS2 UCRT64

注意是 UCRT64，不是普通的 MSYS2 MSYS。后面装的包名也会带 ucrt。

2. 更新包数据库并安装 GCC/GDB

在 MSYS2 UCRT64 里执行：

pacman -Syu

如果它提示关闭窗口，按提示关掉，再重新打开 MSYS2 UCRT64，接着执行：

pacman -Su

安装工具链：

pacman -S --needed mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-gdb mingw-w64-ucrt-x86_64-make

验证：

g++ --version
gdb --version
where g++

where g++ 里应该能看到类似：

C:\msys64\ucrt64\bin\g++.exe

如果看到的是 C:\msys64\usr\bin\g++.exe，大概率是开错了 shell 或 PATH 配错了。

3. 把 UCRT64 加到 Windows PATH

打开 Windows 环境变量，把下面路径加入用户 PATH：

C:\msys64\ucrt64\bin

加完以后，完全关闭 VS Code 和已经打开的终端，再重新打开一个 PowerShell，执行：

g++ --version
gdb --version
where.exe g++

验证点还是一样：优先出现 C:\msys64\ucrt64\bin\g++.exe。

常见坑：只改了系统设置，但 VS Code 是之前打开的，它不会自动吃到新的 PATH。关掉重开最省事。

4. 安装 VS Code 扩展

在 VS Code 扩展页安装 Microsoft 的：

C/C++

扩展标识一般是：

ms-vscode.cpptools

不要同时装一堆名字相似的 C++ 扩展。先只保留官方 C/C++ 扩展，把编译和调试跑通。

5. 建一个最小项目

目录示例：

cpp-demo
├─ .vscode
└─ main.cpp

main.cpp：

#include <iostream>
#include <vector>

int main() {
    std::vector<int> nums{1, 2, 3};
    int sum = 0;
    for (int value : nums) {
        sum += value;
    }
    std::cout << "sum=" << sum << '\n';
    return 0;
}

先别急着配按钮，在 VS Code 终端里手动编译一次：

g++ -std=c++20 -Wall -Wextra -Werror -g main.cpp -o main.exe
.\main.exe

预期输出：

sum=6

本文故意加了 -Wall -Wextra -Werror。早一点让警告变成错误，能逼你把类型转换、未使用变量、返回值这些小坑处理干净。

6. 配置 VS Code 编译任务

创建 .vscode/tasks.json：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build active cpp file",
      "type": "shell",
      "command": "g++",
      "args": [
        "-std=c++20",
        "-Wall",
        "-Wextra",
        "-Werror",
        "-g",
        "${file}",
        "-o",
        "${fileDirname}\\${fileBasenameNoExtension}.exe"
      ],
      "group": {
        "kind": "build",
        "isDefault": true
      },
      "problemMatcher": ["$gcc"],
      "presentation": {
        "reveal": "always",
        "panel": "shared"
      }
    }
  ]
}

按快捷键：

Ctrl + Shift + B

能生成 main.exe 就说明任务配置没问题。

7. 配置断点调试

创建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug active C++ file",
      "type": "cppdbg",
      "request": "launch",
      "program": "${fileDirname}\\${fileBasenameNoExtension}.exe",
      "args": [],
      "stopAtEntry": false,
      "cwd": "${fileDirname}",
      "environment": [],
      "externalConsole": false,
      "MIMode": "gdb",
      "miDebuggerPath": "C:\\msys64\\ucrt64\\bin\\gdb.exe",
      "preLaunchTask": "build active cpp file"
    }
  ]
}

在 sum += value; 这一行打断点，按 F5。如果能停住并看到变量 sum、value，调试流程就通了。

8. 出问题先按这个顺序排

g++ 不是内部或外部命令

PowerShell 里执行：

$env:Path -split ';' | Select-String 'msys64'
where.exe g++

看不到 C:\msys64\ucrt64\bin 就回去改 PATH。改完必须重开终端和 VS Code。

编译能过，调试启动失败

检查 GDB 路径：

Test-Path C:\msys64\ucrt64\bin\gdb.exe

如果返回 False，重新安装：

pacman -S --needed mingw-w64-ucrt-x86_64-gdb

中文输出乱码

先确认终端编码：

chcp

可以临时切到 UTF-8：

chcp 65001

C++ 源文件保存为 UTF-8。不要把源码保存成 ANSI 后再去怀疑编译器。

-Werror 导致编译失败

这不是坏事。比如下面代码会因为未使用变量失败：

int unused = 42;

删除它，或者在代码里使用它。不要第一反应就删掉 -Werror。

9. 最后验收

在 PowerShell 里执行：

g++ -std=c++20 -Wall -Wextra -Werror -g .\main.cpp -o .\main.exe
.\main.exe
where.exe g++
where.exe gdb

在 VS Code 里执行：

Ctrl + Shift + B
F5

检查点：

  • 命令行能编译并输出 sum=6。
  • VS Code 构建任务能生成 exe。
  • F5 能进入断点。
  • where.exe g++ 和 where.exe gdb 都指向 C:\msys64\ucrt64\bin。