同事把一个小工具发过来,功能很朴素:把配置文件里几行 key=value 读出来打印。他说编辑器里没有一条红波浪线,代码看着完全正常,可编译命令跑完之后,终端里是这样一段:

ld.exe: main.cpp:(.text+0xa7): undefined reference to `add(int, int)'
collect2.exe: error: ld returned 1 exit status

他用的命令是 g++ -std=c++20 main.cpp -o app.exe。问题不在代码,在命令:add 这个函数写在另一个 .cpp 文件里,而这条命令只把 main.cpp 交给了编译器。于是流程前面几步都顺利走完,最后一步——把各个目标文件拼在一起——找不到 add 的实现,只好报错。

这件小事值得单独开一篇,因为它把「编译」这个词的模糊之处暴露得很清楚。很多人以为「编译」是一次性的动作:通过就是成功了,不通过就是代码写错了。实际上它是一条流水线,四个阶段各管一件事,报错信息里的措辞、退出码、甚至程序跑起来崩不崩,都能对应到其中某一段。

这篇要解决的问题:一条 g++ 命令到底做了什么;编译错误和链接错误怎么一眼分开;退出码 0、1、139 各意味着什么;多文件项目里声明和定义为什么必须分开;编译选项里哪些是必须加的,哪些加了要付代价。读完你能自己判断:这次的失败是语法问题、符号问题、动态库问题,还是程序真的在内存里踩了雷。

本文按 C++20 写。示例在本机 Windows + MinGW g++ 16.2.0 上实际编译运行过,命令和输出照抄可用。文中涉及 Linux 的部分会单独注明,未在本机实测的内容也会标出来。

「编译过了」这句话本身就不准确

把一条命令拆开看,g++ 从 .cpp 到可执行文件,中间要经过四个阶段。每个阶段都有明确的输入和输出,也都有自己的一套报错方式。

一个源文件的四段流水线
预处理:展开 #include、宏和条件编译,得到 .i
编译:语法语义检查,生成汇编,得到 .s
汇编:把汇编翻成机器码,得到 .o 目标文件
链接:合并多个 .o,解析符号,产出可执行文件

各阶段的具体职责:

  • 预处理只是文本替换。#include <iostream> 会把整份标准库头文件抄进来,一行变几千行;#define 原样展开;#ifdef 决定哪些代码留下。这一步出错通常是找不到头文件。
  • 编译才是大家熟悉的「写错了」阶段:类型不匹配、漏分号、调用了不存在的成员,都在这里报。输出是汇编代码,注意此时还没有任何具体地址。
  • 汇编把汇编翻成机器码,生成一个目标文件(object file,Linux 上是 .o,Windows 上是 .obj)。目标文件里有一张符号表,记录「这个文件提供了哪些函数、还缺哪些函数」。
  • 链接把多个目标文件和库合并,逐个解决「谁提供、谁引用」。只有到这一步,函数调用才会被填上真实地址。

关键概念是编译单元(translation unit):一个 .cpp 加上它包含的所有头文件,构成一次独立编译的范围。编译器一次只看一个编译单元,所以 main.cpp 里调用 add 时,只要看到声明就放行,它不负责去别处找实现——找实现是链接器的活儿。这就是「编辑器没报红,链接却失败」的原因:这两件事根本不在同一个阶段。

完整走查:两个文件相加

把上面那个场景补成能跑的版本。目录里三个文件:

// add.h —— 只放声明,让调用方知道有这个东西
#pragma once
int add(int a, int b);

// add.cpp —— 放定义,真正干活
#include "add.h"
int add(int a, int b) {
  return a + b;
}

// main.cpp
#include <iostream>
#include <string>
#include "add.h"

int main(int argc, char** argv) {
  std::string name = argc > 1 ? argv[1] : "world";
  std::cout << "hello, " << name << "\n";
  std::cout << "1 + 2 = " << add(1, 2) << "\n";
  return 0;
}

正确的构建命令要把两个源文件都列上,并打开常用的警告:

g++ -std=c++20 -Wall -Wextra main.cpp add.cpp -o app.exe

运行结果(本机实测):

hello, world
1 + 2 = 3

退出码是 0。程序正常结束就是要返回 0,这是后续所有「怎么判断失败」的基础:shell 里用 echo $? 看,PowerShell 里看 $LASTEXITCODE,CI 里直接看这一步是否变红。

再看错误版本,只喂一个文件:

g++ -std=c++20 main.cpp -o app.exe

本机输出(原样,路径省略):

ld.exe: main.cpp:(.text+0xa7): undefined reference to `add(int, int)'
collect2.exe: error: ld returned 1 exit status

细看这段话:报错前缀是 ld.exe,也就是链接器,不是编译器;undefined reference 直译是「未定义的引用」,意思是有地方调用了 add(int, int),但没有任何目标文件提供它;collect2.exe: error: ld returned 1 exit status 是编译器驱动转述链接器的失败。看到 ld 这个词,就该往「文件没参与编译、库没链接、签名对不上」这三个方向查,而不是盯着语法。

顺带一个真实存在的小坑:本机把中文当命令行参数传进去,打印出来是 ����。这不是 C++ 把字符串弄坏了,而是控制台代码页(GBK)和程序按 UTF-8 输出之间的错位。系统编程里这类「字节没问题、显示不对」的情况会反复出现,后面讲文件与 I/O 时会专门处理。

现象、原因、先查什么

下面这张表是排错时最省时间的部分。拿到一条报错,先按「哪一段出的问题」分类,再看具体原因,不要一上来就翻代码。

你看到的现象真实原因第一步查什么
error: expected ';' before ...语法错误,编译器在某个记号处卡住了看报错行和它上一行的结尾,漏分号、全角括号、字符串没闭合都常见
undefined reference to `add(int, int)'链接器找不到符号:实现没参与编译,或签名不一致确认该 .cpp 在命令里;确认声明和定义的参数、const、命名空间完全一致
cannot find -lxxx 或 library not found库名或库路径不对,链接器找不到库文件查 -L 路径是否存在、-l 名字是否少了前缀(Linux 上 libxxx.so 对应 -lxxx)
一运行就报 No such file or directory(Linux)或 0xc0000135(Windows)动态库在运行环境里找不到,不是源码问题Linux 用 ldd ./app 看缺哪个;Windows 查同目录和 PATH 里有没有对应 DLL
程序直接崩,退出码 139(Linux)或 -1073741819 / 0xC0000005(Windows)访问了非法内存:空指针、越界、对象已释放用 -g 重新编译,拿 gdb 或 ASan 定位;先查指针生命周期而不是业务逻辑
GLIBCXX_3.4.29 not found 之类运行机器的 libstdc++ 比构建机器旧在目标环境构建,或了解静态链接的代价(体积、许可证、依然依赖 glibc)

这张表里最值得注意的是「退出码」。它比任何日志都直接:进程没有正常收尾,才会出现非 0;139 在 Linux 上等于收到 SIGSEGV(11)后加上 128,Windows 上则是访问违例的异常码。先拿到退出码,再决定是查逻辑还是查内存布局。

多文件项目:声明和定义为啥要分开

上面三个文件的分工不是形式主义,它对应着编译模型本身。

头文件:只有声明,描述「有什么」,被多方包含
源文件:只有定义,描述「怎么做」,各自独立编译
目标文件:每个 .cpp 产出一个,带符号表,可能还留着未解析的引用
可执行文件:链接器把所有目标文件和库合并,补全所有引用

三个必须知道的规则:

  • 头文件只放声明。如果把普通函数定义写进头文件,被两个 .cpp 包含,链接时就会出现 multiple definition。想让函数定义待在头文件里,必须加 inline,或者用模板——它们允许在多个编译单元里重复出现。
  • 每个头文件要能独立编译,加 #pragma once 防重复包含。更稳的检查方式是让一个空的 .cpp 只包含它,单独编译一次;能过,说明头文件没有隐式依赖别的头文件。
  • 只想给本文件用的函数,放进匿名命名空间或声明为 static,给它内部链接,别的编译单元就看不到,也不会撞名。

单文件一把梭

写 demo、刷算法题没问题。文件一过几百行,改一处就全量重编,类与函数的依赖全挤在一起,复用只能靠复制。

按接口分文件

前期多写一个头文件,换来改实现时只重编一个单元、调用方不用关心内部细节。代价是头文件要维护,包含关系要干净。

编译选项:默认值不够用

新手最常见的做法是只写 g++ main.cpp,能跑就行。但在系统编程里,默认配置会漏掉大量警告,也不带调试信息,出事后几乎没法查。几个真正该加的:

选项作用代价
-std=c++20固定语言标准,避免换机器后行为漂移旧编译器不支持;团队要统一
-Wall -Wextra打开常见警告:未使用变量、符号比较、隐式转换等警告会变多,需要真的去处理,而不是关掉
-g保留调试符号,gdb、ASan 的输出才有行号和变量名二进制变大,生产包通常另存符号文件
-O2优化,运行快,内联和常量传播都在这一档编译变慢;单步调试会跳行;未定义行为的后果更难预测
-fsanitize=address在运行时抓越界、重复释放、悬垂访问,是查内存问题最有效的工具程序变慢、内存占用变大;不能用于生产;本机 MinGW 不支持,未实测
优化和未定义行为的关系要提前说清:同一段越界代码,-O0 下可能只是读到一个垃圾值,-O2 下可能被编译器直接优化成「不可能发生」,于是整个分支消失。别用「Release 版没问题」来证明代码正确,那可能只是症状被藏起来了。

边界与代价:这套编译模型的问题

说清楚代价,才知道什么时候该忍、什么时候该换工具。

  • 编译慢。文本包含意味着每个 .cpp 都要把 <iostream> 这类头文件重新解析一遍。工程一大,几分钟的增量编译很常见,这也是预编译头、模块(C++20 modules)被推出来的原因。模块在 GCC 16 上的支持程度建议按项目实测,本文不展开,标为待确认。
  • 没有稳定的 ABI。同一个库,用不同编译器或不同标准库版本编出来的二进制,未必能互相链接。C++ 的二进制分发比 C 难得多,跨语言接口一般退回到 extern "C" 加纯 C 结构。
  • 自由度换来的是责任。语言不替你管内存、不检查越界、默认不拦数据竞争。系统编程选 C++,通常是看中「零成本抽象」:容器和算法写得出来,运行时开销又能控到接近手写 C。代价是上面每一项都要自己兜底。
  • 构建系统是另一层复杂度。文件一多,命令行就管不过来了,迟早要引入 CMake 之类的工具。这不在本篇展开,后面有专门一篇讲构建流程。

换个角度看,这些「缺点」也是 C++ 能待在这个位置的原因:它能直接生成接近操作系统调用的代码,又提供足够的抽象能力写业务逻辑。问题不在语言,在用它的人有没有把边界当回事。

当天能验证的练习

下面几条都可以在本机直接跑,做完再往下读,印象会深很多。

  • 把上面的三个文件建好,分别执行「只编译 main.cpp」和「两个都编译」,把两次报错原文抄下来,标出哪一段是链接器说的。
  • 用 g++ -E main.cpp -o main.i 生成预处理结果,看文件有多大(本机实测:包含 <iostream> 和 <string> 后,main.i 有 32229 行、约 1.2MB,而源文件只有二十来行)。再体会一次「头文件被完整抄进来」是什么意思。
  • 用 g++ -c add.cpp -o add.o 单独编译一次,然后用 nm add.o(或 objdump -t)看符号表,找到 add 那一条。工具是否随编译器安装因环境而异,没有就装 binutils。
  • 写一个空指针写入的程序,分别在 -O0 和 -O2 下编译运行,记录退出码。本机 -O0 实测退出码是 -1073741819(0xC0000005),先打印的内容能看到,之后的语句没执行。
  • 把 add 的定义搬进 add.h,让两个 .cpp 都包含它,观察 multiple definition 报错,再给它加 inline 看报错是否消失。

小结

记住三件事:g++ 不是一步到位,预处理、编译、汇编、链接各有分工;undefined reference 是链接阶段的符号问题,和语法无关;退出码和报错前缀是最快的分流线索,先分类再动手。

知道了代码怎么变成可执行文件,下一个问题就浮出来了:程序跑起来以后,那些变量到底被放在哪、占多大、为什么两个字段相同的结构体 sizeof 不一样。下一篇从类型和对象布局讲起,把这层「看不见的内存摆放」摊开。