三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

Windows下基于MSYS2与MinGW-w64搭建C++学习环境全攻略

发布时间：2026/8/8 19:26:43 三亩地 编程学习日记
Windows下基于MSYS2与MinGW-w64搭建C++学习环境全攻略

1. 项目概述：为什么从环境开始？

如果你刚开始接触侯捷老师的C++课程，或者任何一本经典的C++教材，可能会迫不及待地想直接翻开书，一头扎进那些精妙的语法和设计思想里。但作为一个踩过无数坑的老码农，我必须告诉你，磨刀不误砍柴工。C++学习路上的第一道坎，往往不是指针也不是模板，而是那个看似简单却又处处是陷阱的开发环境。侯捷老师的课程内容深邃，涉及大量现代C++特性和底层机制探讨，一个配置不当的环境会让你在编译第一个“Hello World”时就举步维艰，更别提后续学习STL源码、理解对象模型了。

这个项目笔记的核心，就是解决这个“从零到一”的问题。我们将聚焦于使用MinGW这套工具链在Windows系统上搭建一个纯净、可控、贴近侯捷课程示例的C++编译环境。为什么是MinGW？因为它本质上是GCC（GNU Compiler Collection）在Windows上的移植版本。GCC是C++标准最忠实的实现者之一，也是侯捷老师课程中许多示例代码的默认编译环境。使用MinGW，你能确保编译行为与课程讲解、经典书籍中的描述高度一致，避免因编译器差异（比如微软的MSVC）导致的语法支持度、警告信息甚至运行时行为的微妙不同，这对于夯实基础、理解标准至关重要。

简单来说，这篇笔记的目标是：让你在Windows电脑上，快速搭建一个与侯捷C++课程内容无缝衔接的“学习实验室”。这个环境将用于编译和运行课程中的示例代码，实践各种语言特性，并为后续深入学习（如阅读STL源码、进行内存模型实验）打下坚实基础。无论你是C++新手，还是有一定基础但环境混乱想重整旗鼓的开发者，这篇详尽的配置指南都能帮你扫清障碍。

2. 核心工具链解析：MinGW-w64 vs. MSYS2

在Windows上配置C++环境，你可能会听到MinGW、MinGW-w64、MSYS2、Cygwin等一堆名词，它们之间是什么关系？该选哪个？这是配置前必须理清的概念。

2.1 MinGW 的历史与局限

最初的MinGW（Minimalist GNU for Windows）项目旨在提供一个极简的GNU开发环境，它包含GCC、GDB、Make等工具，并提供了连接Windows API所需的头文件和库。然而，传统的MinGW有一个致命缺陷：它只支持生成32位应用程序。在64位系统成为主流的今天，这显然不够用。

2.2 MinGW-w64：现代解决方案

MinGW-w64是MinGW的一个分支和增强版，正如其名，它最大的贡献就是同时支持32位和64位应用程序的开发。它提供了更完整的运行时库，对C++11/14/17等新标准的支持也更及时。目前，绝大多数情况下我们所说的“MinGW”指的就是MinGW-w64。它是我们搭建环境的首选。

2.3 MSYS2：不仅仅是终端

MSYS2（Minimal SYStem 2）是一个在Windows上提供类Unix环境（主要是Bash shell和一系列Unix工具）的软件发行版。它的核心价值在于提供了一个强大的包管理器：pacman（源自Arch Linux）。通过pacman，你可以像在Linux上一样，轻松地安装、更新和管理成千上万的软件包，其中就包括各种版本的GCC（即MinGW-w64工具链）、GDB、CMake、Git等开发工具。

关键区别与选择建议：

  • 直接下载MinGW-w64安装包：适合喜欢“开箱即用”、手动配置路径的用户。但工具链版本可能较旧，更新麻烦。
  • 使用MSYS2：强烈推荐。它通过包管理解决了工具链的下载、安装、更新和依赖问题。你可以在MSYS2环境中启动多个不同的终端（如MSYS2 UCRT64、MSYS2 MINGW64），每个终端对应一套独立的、纯净的MinGW-w64工具链，互不干扰。这为同时管理多个项目或多个编译器版本提供了极大便利。

注意：MSYS2本身也包含一个“MSYS2”环境，它使用一个特殊的运行时库（msys-2.0.dll），主要用于在Windows上构建Unix风格的软件。我们进行C++开发时，应该使用名为MINGW64或UCRT64的终端，它们提供的才是纯粹的、生成原生Windows程序的MinGW-w64工具链。

2.4 为什么不用Visual Studio？

Visual Studio（特别是MSVC编译器）无疑是Windows平台C++开发的王者，生态完善，调试器强大。但对于学习侯捷课程而言，它有几点不便：

  1. 编译器行为差异：MSVC对C++标准的实现有时与GCC存在细微差别，尤其是在模板、两阶段查找等复杂特性上。课程中的某些示例在MSVC下可能无法编译或产生不同警告。
  2. 项目配置复杂：VS的解决方案和项目文件（.sln, .vcxproj）对于小型学习项目来说略显沉重。而MinGW配合简单的Makefile或直接命令行编译，更能让你理解编译、链接的每一个步骤。
  3. 环境透明度：命令行环境让你对头文件路径、库路径、链接参数有更清晰的掌控，这对于理解构建过程至关重要。

因此，为了获得与课程内容最佳的学习一致性，我们选择MinGW-w64（通过MSYS2安装）。

3. 分步实操：基于MSYS2搭建MinGW-w64环境

下面，我们开始一步步搭建环境。请严格按照步骤操作，我会解释每个步骤的意图。

3.1 下载与安装MSYS2

  1. 访问官网：打开浏览器，访问 MSYS2 官方网站（通常搜索“MSYS2”即可找到）。下载对应的安装程序（通常是msys2-x86_64-xxxxxxxx.exe）。
  2. 运行安装：运行下载的安装程序。安装路径请务必避免中文和空格。我个人的习惯是安装在C:\msys64。这能最大程度避免后续可能出现的各种路径解析问题。
  3. 完成安装：按照安装向导完成即可。安装完成后，不要立即启动MSYS2。

3.2 配置系统环境变量（关键步骤）

为了让系统在任何地方（如CMD、PowerShell、VSCode终端）都能识别到MinGW的工具，我们需要将工具链的bin目录添加到系统的PATH环境变量中。

  1. 假设你的MSYS2安装在C:\msys64。
  2. 我们需要添加的路径是：C:\msys64\mingw64\bin（如果你后续安装的是64位工具链）。这个目录下存放着g++.exe,gcc.exe,gdb.exe,make.exe等关键可执行文件。
  3. 操作步骤：
    • 在Windows搜索框输入“环境变量”，选择“编辑系统环境变量”。
    • 点击“环境变量”按钮。
    • 在“系统变量”区域，找到并选中Path变量，点击“编辑”。
    • 点击“新建”，将C:\msys64\mingw64\bin添加进去。
    • 重要：为了确保优先级，最好将它上移到列表顶部。因为你的系统里可能已经安装了其他版本的GCC或开发工具。
    • 点击“确定”保存所有更改。

3.3 启动MSYS2并安装工具链

  1. 从开始菜单找到并启动MSYS2 UCRT64（或MSYS2 MINGW64）。UCRT是Windows 10之后的新C运行时库，更现代，推荐使用。
  2. 首次启动后，首先更新软件包数据库和基础包。在打开的终端中依次执行以下命令：
    pacman -Syu
    这个命令会同步包数据库并升级所有核心包。过程中可能会提示你关闭终端，按照提示操作，重新启动MSYS2 UCRT64，然后再次运行：
    pacman -Su
    以确保所有更新完成。
  3. 安装MinGW-w64工具链、GDB调试器和Make构建工具：
    pacman -S --needed base-devel mingw-w64-ucrt-x86_64-toolchain
    base-devel包含了一些基本的开发工具（如make, automake等）。mingw-w64-ucrt-x86_64-toolchain这个元包会自动安装GCC、G++、GDB等一系列编译调试工具。
  4. 安装过程中，终端会显示要安装的软件包列表并询问是否继续，输入Y并按回车确认。

3.4 验证安装

安装完成后，在新的终端窗口（可以是刚才的MSYS2终端，也可以是系统自带的CMD或PowerShell）中，输入以下命令验证：

g++ --version gdb --version make --version

如果每条命令都能正确输出版本信息（例如g++ (Rev6, Built by MSYS2 project) 13.2.0），恭喜你，MinGW-w64工具链已经安装并配置成功！

实操心得：很多同学在配置后，在CMD里输入g++提示“不是内部或外部命令”，问题99%出在环境变量上。请务必检查：1. 路径是否正确（特别是mingw64\bin）；2. 是否添加到了系统变量的Path中；3. 添加后是否重启了终端窗口（环境变量需要重新加载）。一个快速测试方法是，打开一个新的CMD窗口再试。

4. 第一个C++程序：从编译到调试

环境搭好了，我们来点实际的。让我们用一个简单的程序来测试整个工作流。

4.1 编写源代码

在你喜欢的位置（例如D:\CppProjects）创建一个文件夹，比如叫test_hello。在里面用任何文本编辑器（推荐VSCode、Notepad++，甚至记事本）创建一个文件，命名为hello.cpp，输入以下内容：

#include <iostream> #include <vector> int main() { std::cout << "Hello, Hou Jie's C++ World!" << std::endl; // 使用一点C++11特性，测试编译器支持度 std::vector<int> vec = {1, 2, 3, 4, 5}; for (auto& num : vec) { std::cout << num << " "; } std::cout << std::endl; return 0; }

这个程序不仅输出问候语，还使用了C++11的范围for循环和初始化列表，用来测试编译器对新标准的支持。

4.2 命令行编译与运行

打开MSYS2 UCRT64终端，使用cd命令切换到你的hello.cpp所在目录。

  1. 基本编译：

    g++ hello.cpp -o hello.exe
    • g++: 调用C++编译器。
    • hello.cpp: 源文件。
    • -o hello.exe:-o指定输出文件名。在Windows上，可执行文件通常有.exe后缀。

  2. 运行程序：

    ./hello.exe

    你应该能看到两行输出。

4.3 理解编译选项

侯捷老师的课程会深入C++的方方面面，很多特性需要特定的编译器选项来开启或控制。

  • 指定C++标准：使用-std=c++11,-std=c++14,-std=c++17,-std=c++20等。例如，要确保使用C++17标准编译：

    g++ -std=c++17 hello.cpp -o hello.exe

  • 显示所有警告：-Wall和-Wextra选项让编译器变得“挑剔”，这能帮你发现很多潜在问题，是良好的编程习惯。

    g++ -std=c++17 -Wall -Wextra hello.cpp -o hello.exe

  • 生成调试信息：-g选项会在可执行文件中加入调试符号，这是使用GDB进行源代码级调试的前提。

    g++ -std=c++17 -Wall -Wextra -g hello.cpp -o hello_debug.exe

  • 优化级别：-O0（不优化，调试用），-O1,-O2,-O3（优化程度递增）。学习阶段通常用-O0或-O1以便于调试。

4.4 使用GDB进行简单调试

调试是理解程序运行逻辑、排查错误的必备技能。我们用刚才生成的hello_debug.exe来演示。

  1. 启动GDB：
    gdb hello_debug.exe
  2. 在GDB提示符(gdb)下，可以输入命令：
    • list或l: 列出源代码。
    • break main或b main: 在main函数开头设置断点。
    • run或r: 运行程序，直到断点处停止。
    • next或n: 执行下一行代码（不进入函数内部）。
    • step或s: 执行下一行代码（会进入函数内部）。
    • print vec或p vec: 打印变量vec的值。
    • continue或c: 继续运行直到下一个断点或程序结束。
    • quit或q: 退出GDB。

一个简单的调试会话可能如下：

(gdb) b main (gdb) r (gdb) n // 执行完cout语句 (gdb) p vec $1 = std::vector of length 5, capacity 5 = {1, 2, 3, 4, 5} (gdb) c

5. 集成开发环境（IDE）配置：以VSCode为例

虽然命令行是根本，但一个好的IDE能极大提升学习效率。VSCode轻量、免费、插件丰富，是搭配MinGW学习C++的绝佳选择。

5.1 安装必要插件

在VSCode的扩展市场（Ctrl+Shift+X）中搜索并安装：

  1. C/C++(Microsoft)：提供代码智能感知（IntelliSense）、调试、浏览等功能。
  2. Code Runner：用于快速运行单文件程序。

5.2 配置C/C++插件

这是最关键的一步，告诉VSCode你的编译器和头文件在哪里。

  1. 在你的项目文件夹（test_hello）下，创建一个.vscode文件夹。
  2. 在.vscode文件夹内创建两个文件：tasks.json和launch.json。

tasks.json- 定义构建任务

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

这个任务定义了如何编译当前打开的文件。按Ctrl+Shift+B即可运行此任务进行编译。

launch.json- 定义调试配置

{ "version": "0.2.0", "configurations": [ { "name": "(gdb) Launch", "type": "cppdbg", "request": "launch", "program": "${fileDirname}\\${fileBasenameNoExtension}.exe", "args": [], "stopAtEntry": false, "cwd": "${fileDirname}", "environment": [], "externalConsole": true, // 使用外部控制台，避免VSCode终端输入问题 "MIMode": "gdb", "miDebuggerPath": "C:\\msys64\\mingw64\\bin\\gdb.exe", // 根据你的实际路径修改！ "setupCommands": [ { "description": "Enable pretty-printing for gdb", "text": "-enable-pretty-printing", "ignoreFailures": true } ], "preLaunchTask": "build with g++" // 调试前自动执行上面的构建任务 } ] }

注意miDebuggerPath必须指向你安装的gdb.exe的绝对路径。preLaunchTask确保了在启动调试前会自动编译最新代码。

5.3 配置IntelliSense

为了让VSCode的代码补全和跳转更准确，需要配置C/C++插件的包含路径。

按Ctrl+Shift+P，输入C/C++: Edit Configurations (UI)，打开配置界面。

  • 在编译器路径中，填入C:\msys64\mingw64\bin\g++.exe。
  • 在IntelliSense 模式中，选择windows-gcc-x64。
  • 在包含路径中，添加MinGW的头文件目录，例如C:\msys64\mingw64\include和C:\msys64\mingw64\include\c++\13.2.0（版本号可能不同）。通常编译器路径设置正确后，插件会自动探测。

配置完成后，打开hello.cpp，你应该能获得准确的代码提示、悬停查看定义等功能。按F5即可开始调试，程序会在外部控制台运行，断点、变量查看等功能都能正常使用。

注意事项：VSCode的C/C++插件配置有时会因更新或缓存出现问题。如果代码提示突然失灵，可以尝试：1. 按Ctrl+Shift+P执行C/C++: Reset IntelliSense Database；2. 删除项目下.vscode文件夹中的ipch缓存文件夹；3. 重启VSCode。

6. 进阶配置：多文件项目与Makefile

侯捷老师的课程后期必然会涉及多文件项目（.h头文件和多个.cpp源文件）。手动编译每个文件并链接非常繁琐，这时就需要构建工具。

6.1 手动编译多文件

假设你有以下项目结构：

project/ ├── main.cpp ├── math_utils.h └── math_utils.cpp

math_utils.h:

#pragma once int add(int a, int b);

math_utils.cpp:

#include "math_utils.h" int add(int a, int b) { return a + b; }

main.cpp:

#include <iostream> #include "math_utils.h" int main() { std::cout << "3 + 4 = " << add(3, 4) << std::endl; return 0; }

编译命令如下：

g++ -std=c++17 -Wall -c math_utils.cpp -o math_utils.o g++ -std=c++17 -Wall -c main.cpp -o main.o g++ main.o math_utils.o -o project.exe

-c选项表示“只编译不链接”，生成目标文件（.o）。最后一步将多个目标文件链接成最终的可执行文件。

6.2 使用Makefile自动化

当文件增多时，上述命令难以维护。Makefile可以定义构建规则。在项目根目录创建Makefile文件（无后缀）：

CXX = g++ CXXFLAGS = -std=c++17 -Wall -Wextra -g TARGET = project.exe OBJS = main.o math_utils.o all: $(TARGET) $(TARGET): $(OBJS) $(CXX) $(OBJS) -o $(TARGET) main.o: main.cpp math_utils.h $(CXX) $(CXXFLAGS) -c main.cpp -o main.o math_utils.o: math_utils.cpp math_utils.h $(CXX) $(CXXFLAGS) -c math_utils.cpp -o math_utils.o clean: rm -f *.o $(TARGET) .PHONY: all clean

解释：

  • CXX和CXXFLAGS是变量，定义了编译器和编译选项。
  • TARGET是最终目标文件。
  • OBJS是所有需要的目标文件列表。
  • all是默认目标，依赖于$(TARGET)。
  • $(TARGET): $(OBJS)规则说明目标文件依赖于所有.o文件，链接命令是$(CXX) $(OBJS) -o $(TARGET)。
  • 下面的规则定义了每个.o文件如何从其对应的.cpp和.h文件生成。
  • clean目标用于清理生成的文件。
  • .PHONY声明all和clean是“伪目标”，不代表实际文件。

在终端中，只需输入make，就会自动执行编译链接；输入make clean清理文件。这大大简化了构建过程。

6.3 使用CMake（更现代的选择）

对于更复杂的项目，CMake是跨平台构建的事实标准。它生成对应平台（如Makefile或Visual Studio项目）的构建文件。创建一个CMakeLists.txt：

cmake_minimum_required(VERSION 3.10) project(MyProject LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_CXX_EXTENSIONS OFF) add_executable(project_exe main.cpp math_utils.cpp math_utils.h )

然后在项目目录下执行：

mkdir build cd build cmake -G "MinGW Makefiles" .. make

-G "MinGW Makefiles"指定生成适用于MinGW的Makefile。执行后会在build目录下生成project_exe.exe。

7. 常见问题与排查技巧实录

即使按照步骤操作，你也可能会遇到一些问题。这里汇总了一些典型问题及其解决方法。

7.1 编译错误：fatal error: iostream: No such file or directory

  • 问题：编译器找不到标准库头文件。
  • 原因：环境变量PATH中的MinGWbin路径正确，但编译器内部配置的头文件搜索路径不对，或者安装的MinGW工具链不完整。
  • 解决：
    1. 检查MinGW安装是否完整。在MSYS2终端运行pacman -Qs gcc查看gcc包是否已安装。
    2. 检查头文件是否存在。去C:\msys64\mingw64\include\c++\目录下查看是否有对应版本的头文件目录。
    3. 如果使用VSCode，确保C/C++插件配置中的“编译器路径”指向正确的g++.exe。

7.2 链接错误：undefined reference toWinMain'`

  • 问题：通常发生在编译Windows GUI程序（需要WinMain入口）时，但你写的是控制台程序（main入口）。
  • 原因：链接器默认寻找WinMain。或者，你误将源文件后缀命名为.c却被当作C++编译，C++的main函数编译后名称修饰（name mangling）与C不同。
  • 解决：
    1. 确保你的程序入口是int main()。
    2. 在链接时添加-mconsole选项，明确告诉链接器生成控制台程序：g++ ... -mconsole。
    3. 确保源文件扩展名为.cpp或.cc，以便编译器自动识别为C++。

7.3 运行时错误：程序一闪而过

  • 问题：在资源管理器双击.exe或某些IDE中运行，控制台窗口打开后立即关闭。
  • 原因：程序执行完毕，控制台自动关闭。这是正常现象，并非错误。
  • 解决：
    1. 在终端中运行：在CMD、PowerShell或MSYS2终端中，用./your_program.exe运行。
    2. 在代码末尾暂停：在main函数return 0;前添加system("pause");（需要#include <cstdlib>）或std::cin.get();。注意：system("pause")不是跨平台的，仅用于临时调试。
    3. 在IDE中配置：在VSCode的launch.json中，设置"externalConsole": true，这样调试时会弹出独立控制台窗口，程序结束后窗口会保持。

7.4 VSCode智能感知（IntelliSense）报红，但编译正常

  • 问题：代码下有红色波浪线，提示找不到头文件或符号，但用g++命令行编译完全成功。
  • 原因：VSCode的C/C++插件使用的IntelliSense引擎（基于clang）与你的实际编译器（g++）配置不一致，导致头文件搜索路径、预定义宏不同。
  • 解决：
    1. 确保C/C++: Edit Configurations (UI)中的“编译器路径”绝对正确。
    2. 尝试在.vscode/c_cpp_properties.json（通过UI配置会自动生成）中，将compilerPath下的includePath和defines设置为空数组[]，并勾选"compilerArgs"选项，让插件自动从指定的编译器推断配置。这通常是最可靠的方法。
    3. 执行命令C/C++: Reset IntelliSense Database并重启VSCode。

7.5 安装MSYS2时下载速度极慢或失败

  • 问题：pacman -Syu更新或安装包时卡住或报错。
  • 原因：默认源服务器可能在国外，网络连接不稳定。
  • 解决：更换为国内镜像源。编辑MSYS2安装目录下的etc\pacman.d文件夹中的三个镜像列表文件：mirrorlist.mingw32,mirrorlist.mingw64,mirrorlist.msys。 在文件开头添加国内镜像源，例如中科大的源：
    Server = https://mirrors.ustc.edu.cn/msys2/mingw/i686/ Server = https://mirrors.ustc.edu.cn/msys2/mingw/x86_64/ Server = https://mirrors.ustc.edu.cn/msys2/msys/$arch/
    保存后，再次运行pacman -Syu。

环境配置是C++学习之旅的基石，一个稳定、透明的环境能让你更专注于语言本身和侯捷老师讲授的精髓。这套基于MSYS2和MinGW-w64的方案，在Windows上为你提供了一个接近Linux开发体验的、标准一致的C++学习平台。当你熟悉了命令行编译、调试和简单的构建工具后，你会发现理解那些复杂的语言特性、内存布局和标准库实现，都变得更加顺理成章。记住，遇到问题多查（使用g++ --help、man gcc（在MSYS2中）、搜索引擎）、多试，每一个解决的配置问题，都是你成为更成熟开发者的垫脚石。

编程学习 学习日记 实战经验
← 返回列表