Windows 下 VS Code + MSYS2 MinGW C++ 环境搭建笔记

概述

这份文档记录当前项目的 C++ 开发环境配置。目标是：在 VS Code 中按 F5 自动完成编译、生成、启动调试。

当前方案使用：

• 编译器：MSYS2 MinGW g++.exe
• 调试器：MSYS2 MinGW gdb.exe
• 编辑器：Visual Studio Code
• 代码提示：clangd
• 构建输出目录：build

需要安装什么

1. 安装 VS Code。

2. 安装 MSYS2。https://www.msys2.org/

   当前路径是：

   C:\msys64

3. 在 MSYS2 里安装 MinGW 编译工具链。

   打开 MSYS2 MinGW x64 终端，执行：

   pacman -Syu
   pacman -S --needed mingw-w64-x86_64-gcc mingw-w64-x86_64-gdb

4. 确认编译器和调试器存在：

   C:\msys64\mingw64\bin\g++.exe
   C:\msys64\mingw64\bin\gdb.exe

5. VS Code 建议安装这些扩展：

   • C/C++，扩展 ID：ms-vscode.cpptools
   • clangd，扩展 ID：llvm-vs-code-extensions.vscode-clangd

如果使用 clangd，可以把 Microsoft C/C++ IntelliSense 关掉：

"C_Cpp.intelliSenseEngine": "disabled"

推荐项目结构

单文件学习项目可以这样放：

项目目录
├─ .vscode
│  ├─ tasks.json
│  ├─ launch.json
│  ├─ c_cpp_properties.json
│  └─ settings.json
├─ .clangd
├─ build
└─ hello.cpp

build 目录用于保存编译生成的 .exe、调试符号和中间文件。

tasks.json 做了什么

tasks.json 负责“怎么编译”。

当前有两个任务：

1. create build folder

   作用是创建 build 文件夹。

   {
       "label": "create build folder",
       "type": "process",
       "command": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
       "args": [
           "-NoProfile",
           "-ExecutionPolicy",
           "Bypass",
           "-Command",
           "New-Item -ItemType Directory -Force -Path '${workspaceFolder}\\build' | Out-Null"
       ],
       "problemMatcher": []
   }

2. build active C++ file

   作用是编译当前打开的 .cpp 文件。

   {
       "label": "build active C++ file",
       "type": "process",
       "command": "C:\\msys64\\mingw64\\bin\\g++.exe",
       "args": [
           "-std=c++20",
           "-g",
           "-Wall",
           "-Wextra",
           "${file}",
           "-o",
           "${workspaceFolder}\\build\\${fileBasenameNoExtension}.exe"
       ],
       "options": {
           "cwd": "${workspaceFolder}",
           "env": {
               "PATH": "C:\\msys64\\mingw64\\bin;${env:PATH}"
           }
       },
       "problemMatcher": [
           "$gcc"
       ],
       "group": {
           "kind": "build",
           "isDefault": true
       },
       "dependsOn": [
           "create build folder"
       ]
   }

关键字段说明：

• type: "process"：直接运行程序，不经过 bash 或 PowerShell 解释命令。这个很重要。
• command：指定真正的编译器，也就是 g++.exe。
• args：传给 g++ 的参数。
• -std=c++20：使用 C++20 标准。
• -g：生成调试信息，GDB 调试需要它。
• -Wall -Wextra：打开常用警告。
• ${file}：当前打开的源文件。
• ${workspaceFolder}：当前 VS Code 打开的项目根目录。
• ${fileBasenameNoExtension}：当前文件名，不带扩展名。例如 hello.cpp 会变成 hello。
• PATH：把 C:\msys64\mingw64\bin 放进环境变量，防止 g++ 找不到 MSYS2 的 DLL。
• dependsOn：先创建 build 文件夹，再编译。
• problemMatcher: "$gcc"：让 VS Code 能识别 GCC 的报错，并跳转到对应代码行。

为什么不用 type: "shell"：

如果 VS Code 默认终端是 MSYS2 Bash，type: "shell" 会让 bash 执行命令。bash 会把 Windows 路径里的反斜杠当转义字符，导致：

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

被解析成类似：

C:msys64mingw64bing++.exe

然后就会报：

bash: C:msys64mingw64bing++.exe: 未找到命令

所以这里使用 type: "process"。

launch.json 做了什么

launch.json 负责“怎么调试”。

按 F5 时，VS Code 会读取这里的调试配置。

当前配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "F5: Build and debug active C++ file",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/build/${fileBasenameNoExtension}.exe",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "environment": [
                {
                    "name": "PATH",
                    "value": "C:\\msys64\\mingw64\\bin;${env:PATH}"
                }
            ],
            "externalConsole": false,
            "MIMode": "gdb",
            "miDebuggerPath": "C:\\msys64\\mingw64\\bin\\gdb.exe",
            "preLaunchTask": "build active C++ file",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ]
        }
    ]
}

关键字段说明：

• name：调试配置名称，按 F5 时可以看到。
• type: "cppdbg"：使用 Microsoft C/C++ 扩展提供的 GDB/LLDB 调试器入口。
• request: "launch"：启动一个新程序进行调试。
• program：要调试的 exe 路径。
• program 使用 /：GDB 更容易正确识别路径，避免反斜杠转义问题。
• cwd：程序运行时的工作目录。
• environment：给调试程序补充环境变量。
• MIMode: "gdb"：使用 GDB 调试。
• miDebuggerPath：指定 GDB 的完整路径。
• preLaunchTask：调试前先执行哪个编译任务。
• externalConsole: false：使用 VS Code 内部调试控制台/终端。
• setupCommands：开启 GDB pretty printing，让 STL 容器显示更友好。

按 F5 的完整流程是：

F5
↓
读取 launch.json
↓
发现 preLaunchTask = build active C++ file
↓
执行 tasks.json 里的 build active C++ file
↓
先创建 build 目录
↓
调用 g++ 编译当前 cpp
↓
生成 build/当前文件名.exe
↓
调用 gdb 调试这个 exe

c_cpp_properties.json 做了什么

c_cpp_properties.json 是 Microsoft C/C++ 扩展的配置文件，主要影响 IntelliSense、头文件搜索、C++ 标准等。

如果你已经设置：

"C_Cpp.intelliSenseEngine": "disabled"

那这个文件对代码提示的作用会变小，因为代码提示主要交给 clangd。

不过保留它仍然有用，方便 C/C++ 扩展识别项目环境。

示例：

{
    "version": 4,
    "configurations": [
        {
            "name": "MinGW x64",
            "compilerPath": "C:/msys64/mingw64/bin/g++.exe",
            "intelliSenseMode": "windows-gcc-x64",
            "cppStandard": "c++20",
            "cStandard": "c17",
            "includePath": [
                "${workspaceFolder}/**"
            ]
        }
    ]
}

.clangd 做了什么

.clangd 是 clangd 的项目配置文件。

它不负责真正编译，而是负责让 clangd 正确理解你的项目。

当前配置：

CompileFlags:
  Compiler: C:/msys64/mingw64/bin/g++.exe
  Add:
    - -std=c++20

作用：

• 让 clangd 按 MinGW g++ 的环境解析代码。
• 让 clangd 使用 C++20 标准。
• 让 #include <iostream>、#include <vector> 等标准库头文件更容易被正确识别。

新项目复制步骤

以后新建一个 C++ 项目时，可以按这个流程：

1. 新建项目文件夹。

2. 在项目根目录创建 .vscode 文件夹。

3. 复制这几个文件：

   .vscode/tasks.json
   .vscode/launch.json
   .vscode/c_cpp_properties.json
   .clangd

4. 确认 MSYS2 路径正确：

   C:\msys64\mingw64\bin\g++.exe
   C:\msys64\mingw64\bin\gdb.exe

5. 打开一个 .cpp 文件。

6. 按 F5。

7. 如果弹出配置选择，选择：

   F5: Build and debug active C++ file

常见问题

bash: C:msys64mingw64bing++.exe: 未找到命令

原因：

VS Code 用 MSYS2 Bash 执行了 Windows 路径，反斜杠被 bash 当作转义符。

解决：

tasks.json 里使用：

"type": "process"

不要用：

"type": "shell"

g++ 能启动，但 cc1plus.exe 失败

如果出现类似 -1073741515 的退出码，通常表示找不到 DLL。

解决：

确认任务和调试配置里都有：

"PATH": "C:\\msys64\\mingw64\\bin;${env:PATH}"

F5 没有先编译

检查 launch.json 里是否有：

"preLaunchTask": "build active C++ file"

并且 tasks.json 里任务名称必须完全一致：

"label": "build active C++ file"

断点不生效

检查 tasks.json 编译参数里是否有：

"-g"

没有 -g，GDB 就缺少调试信息。

VS Code 选到了 C/C++ Runner 的配置

如果 launch.json 里出现：

C/C++ Runner: Debug Session

可能会干扰当前配置。建议删除那段配置，只保留自己的 F5: Build and debug active C++ file。

当前项目的最小 hello.cpp

#include <iostream>

int main()
{
    std::cout << "Hello, C++!" << std::endl;
    return 0;
}

按 F5 后，期望输出：

Hello, C++!