前言
很多人把「搭建 C++ 环境」理解成执行一条安装命令，装完g++就算完成。实际上，一个能支撑日常开发的 Linux 环境至少包含四层：编译器与标准库、链接器与二进制工具、调试器、构建系统。缺任何一层，都会在某个具体环节卡住，而报错信息往往不会直接指向缺失的那一层。
第二个常见误解是把 IDE 当成环境本身。VS Code、CLion、Qt Creator 提供的只是编辑、索引和调试前端，真正干活的是底下的 GCC/Clang、GDB/LLDB 和 CMake。先把命令行链路走通，换编辑器时就不会被配置文件牵着走。
第三个问题是照抄包名。Debian 系、Fedora 系、Arch 系的软件包划分并不相同，build-essential在 Fedora 上并不存在。本文以 Debian/Ubuntu 为主线，同时给出另外两个发行版的对应命令，并按「安装—编译—调试—工程化」的顺序把整条链路讲清楚。
一、从源文件到可执行文件：工具链到底由什么组成
g++不是单一程序，而是一个驱动程序（driver）。它根据文件后缀和选项，依次调用预处理器、编译器前端、汇编器和链接器。加上-v可以看到它实际调用了哪些子进程；-E、-S、-c则让流程分别停在预处理、汇编、目标文件三个阶段。
| 阶段 | 典型工具 | 输入 | 输出 |
|---|
| 预处理 | cpp或cc1plus内部完成 | .cpp、.h | 展开后的翻译单元 |
| 编译 | cc1plus | 预处理结果 | 汇编代码.s |
| 汇编 | as | .s | 目标文件.o |
| 链接 | collect2调用ld | .o、静态库、动态库 | 可执行文件或.so |
| 调试 | gdb | 带调试信息的可执行文件 | 运行时观察 |
| 构建 | make、ninja，由 CMake 生成 | 构建描述 | 构建产物 |
理解这张表的价值在于定位错误：error:开头的诊断来自编译阶段，通常是语法、类型、头文件问题；undefined reference来自链接阶段，说明符号声明存在但定义没参与链接；而运行时的Segmentation fault则要回到调试器里看。
二、按发行版安装工具链
Debian/Ubuntu 用元包build-essential一次装齐g++、make、libc6-dev等：
sudo apt update
sudo apt install -y build-essential gdb cmake ninja-build gitFedora 系的包名不同，C++ 编译器是gcc-c++：
sudo dnf install -y gcc-c++ gdb cmake ninja-build gitArch 系用base-devel组，它会带上gcc、make等基础工具：
sudo pacman -S --needed base-devel gdb cmake ninja git装完先确认版本，避免出现「命令找不到」或版本过旧：
g++ --version
gdb --version
cmake --version这里有一个高频陷阱：只安装gcc而不安装g++。gcc驱动可以编译.cpp文件，但它默认不链接libstdc++，于是标准库符号全部缺失，报错形如undefined reference to 'std::cout'。判断方法很简单：先看g++命令是否存在；存在时，g++ -print-file-name=libstdc++.so应当给出一个真实路径，而不是原样回显文件名。
三、手工编译与 GDB 调试的最小闭环
先用一个小程序把编译选项走一遍：
// 适用于 C++17
#include <iostream>
#include <string>
#include <vector>
int main() {
std::vector<std::string> names{"alpha", "beta", "gamma"};
for (const auto& name : names) {
std::cout << name << '\n';
}
return 0;
}编译命令建议至少带上这几项：
g++ -std=c++17 -Wall -Wextra -Wpedantic -g -O0 hello.cpp -o hello-std=c++17固定语言标准，避免不同 GCC 默认值带来的差异；-Wall -Wextra打开常用警告集合，但它们并不是「全部警告」；-g生成调试信息；-O0关闭优化，保证变量和行号在调试时可信。要注意-Wall并不包含所有诊断，遇到可疑代码时还可以叠加-Wshadow、-Wconversion等，按项目需要选择。
进入调试器后，常用的动作只有几个：
gdb ./hello在 GDB 提示符下，break main在入口下断点，run启动程序，next单步跳过函数调用，step进入函数，print names.size()求值，info locals看当前栈帧的局部变量，bt打印调用栈，continue继续运行，quit退出。
对于崩溃类问题，非交互模式更省事：gdb -batch -ex run -ex bt ./hello会直接跑到崩溃点并打印回溯。若程序在容器或远程机器上崩溃，则需要 core dump：先ulimit -c unlimited，再确认/proc/sys/kernel/core_pattern把 core 文件写到哪里——不少发行版默认交给 systemd-coredump 接管，此时文件不在当前目录，而在系统日志或/var/lib/systemd/coredump下。
另外建议在开发期打开运行时检查器：
g++ -std=c++17 -g -O1 -fsanitize=address,undefined hello.cpp -o hello_sanAddressSanitizer 能发现越界、释放后使用、重复释放等问题，UndefinedBehaviorSanitizer 能报告有符号溢出、空指针解引用等。它们依赖编译器运行时库，GCC 与 Clang 都支持，但具体可用性以各自版本文档为准；检查器只是提高发现概率，不能证明程序没有未定义行为。
四、用 CMake 组织多文件工程
单文件可以手敲命令，多文件就必须有构建描述。一个最小但规范的目录结构如下：
demo/
CMakeLists.txt
include/math_utils.h
src/math_utils.cpp
src/main.cpp对应的CMakeLists.txt：
cmake_minimum_required(VERSION 3.16)
project(demo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)
add_library(math_utils src/math_utils.cpp)
target_include_directories(math_utils PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)
add_executable(demo src/main.cpp)
target_link_libraries(demo PRIVATE math_utils)CMAKE_CXX_EXTENSIONS OFF让编译器使用严格的-std=c++17而不是-std=gnu++17，避免无意中依赖 GNU 扩展。target_include_directories使用PUBLIC，引用该库的目标会自动继承头文件路径；target_link_libraries用PRIVATE，因为可执行文件不需要把依赖继续传给别人。
配置与构建分两步，构建目录放在源码树之外：
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -jCMAKE_BUILD_TYPE只在单配置生成器（Makefile、Ninja）下有意义；Visual Studio 这类多配置生成器要在构建时用--config指定。Debug 通常会加-g，Release 会加优化并定义NDEBUG，所以调试时不要用 Release 产物。
如果还要让编辑器提供准确的补全和跳转，可以在配置阶段导出编译数据库：
cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON生成的build/compile_commands.json记录了每个源文件的完整编译命令，clangd 等语言服务器直接读取它，就不再需要手写includePath。这个变量只对 Makefile 和 Ninja 生成器有效，这是使用它时需要注意的限制。
远程或嵌入式场景不必把源码拷到目标机：目标机上运行gdbserver :2345 ./demo，开发机上用gdb ./demo后执行target remote 目标地址:2345，再照常下断点。符号文件仍然来自开发机上的可执行文件，所以两边的构建产物必须一致，否则断点位置会对不上。
用 VS Code 调试时，launch.json的核心字段是程序路径和调试器类型：
{
"version": "0.2.0",
"configurations": [
{
"name": "gdb",
"type": "cppdbg",
"request": "launch",
"program": "${workspaceFolder}/build/demo",
"cwd": "${workspaceFolder}",
"MIMode": "gdb",
"setupCommands": [
{ "text": "-enable-pretty-printing", "ignoreFailures": true }
]
}
]
}常见坑点
- ❌ 只装
gcc就编译 C++，报undefined reference to 'std::cout'。✅ 安装g++（Debian 系是build-essential），并用g++驱动编译链接。 - ❌ 用
-O2产物调试，发现变量显示为<optimized out>。✅ 调试配置用-O0 -g，需要一定优化时用-Og -g。 - ❌ 链接时把
-lmylib写在目标文件之前，符号解析失败。✅ 库参数放在使用它的目标文件之后，GCC 的链接顺序是有意义的。 - ❌ 运行时提示
cannot open shared object file，就以为是编译失败。✅ 这是动态链接器找不到.so，用ldd检查依赖，再设置RPATH或LD_LIBRARY_PATH。 - ❌ 直接在源码目录执行
cmake .，生成物和源码混在一起。✅ 用cmake -S . -B build做 out-of-source 构建。 - ❌ 把
-Wall当成「开启全部警告」。✅ 它只是常用集合，按需追加-Wextra、-Wpedantic、-Wconversion等。 - ❌ 用
sudo编译项目，产物属主变成 root。✅ 用普通用户构建，只有安装系统包时才用sudo。 - ❌ 崩溃后找不到 core 文件，就断言程序没有崩溃。✅ 检查
ulimit -c与core_pattern，容器里还要确认 core 是否被禁用。
总结
| 目标 | 关键命令或配置 |
|---|
| 安装工具链 | apt install build-essential gdb cmake |
| 严格标准编译 | g++ -std=c++17 -Wall -Wextra -g -O0 |
| 运行时检查 | -fsanitize=address,undefined |
| 配置工程 | cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug |
| 构建 | cmake --build build -j |
| 调试 | gdb ./build/demo，必要时-batch -ex run -ex bt |
环境搭建的本质是把「编辑—编译—链接—调试」这条链路的每一段都变成可观察、可复现的。发行版差异只影响安装命令，不影响后面的方法论；把构建目录、语言标准和调试信息这三件事固定下来，团队里就不会再出现「我这里能编过」的争论。
