C++ 翻译单元：独立编译与多文件程序边界
03 翻译单元才是编译器真正看到的文件
你在编辑器里打开 main.cc，看到 #include "math.h"，自然觉得编译器也能"看到" math.h。实际上编译器根本不看 math.h 这个文件。它看的是预处理之后的那份合成文本：main.cc 加上它通过 #include 直接和间接拉进来的所有头文件内容，经过宏替换和条件编译剪裁之后的最终形态。C++ 标准给这份合成文本起了一个专门的名字，叫翻译单元（translation unit）。一个翻译单元对应一个 .cc 文件及其预处理展开后的完整文本。项目里有几个 .cc，经过预处理就形成几个翻译单元，编译器独立处理每一个，处理顺序无关。
拿出实际的代码来看这个过程。准备三个文件：math.h 声明 Add 函数，math.cc 提供 Add 的实现，main.cc 调用 Add。
// math.h
#ifndef MATH_H_
#define MATH_H_int Add(int left, int right);
#endif
// math.cc
#include "math.h"
int Add(int left, int right) {
return left + right;
}
// main.cc
#include "math.h"#include <iostream>int main() {
std::cout << Add(20, 22) << "\n";
return 0;
}
验证的第一步是确认两个 .cc 可以各自独立编译成目标文件：
clang++ -std=c++20 -Wall -c main.cc -o main.o # 通过
clang++ -std=c++20 -Wall -c math.cc -o math.o # 通过
-c 的含义是"只编译不链接"。执行第一条命令时，math.cc 甚至不需要存在于磁盘上。编译器处理 main.cc 这个翻译单元时，面对的是 main.cc 预处理后的文本：最先是 math.h 里 Add 的函数声明（也就是 int Add(int, int); 这一行），接着是 <iostream> 展开后近十万行的标准库声明，最后是 main 函数的定义。编译器从这份文本里读到了 Add 的声明，于是它有能力检查 Add(20, 22) 这个调用点：参数数量对不对、每个参数的类型能不能隐式转换到 int、返回值类型和 << 运算符的期望是否匹配。这些检查全部在翻译单元内部完成，无需任何外部信息。
但编译器在 main.cc 的翻译单元里找不到 Add 的函数体。函数体在另一个文件 math.cc 里，而编译器处理 main.cc 时根本不会去读 math.cc。编译器的处理逻辑是：声明说这个函数存在，参数类型也吻合，这一关算过。函数体在哪里、是不是真的存在，留给链接器去操心。编译器在产出的 main.o 中为 Add 创建一个"未定义符号"记录，标注"此处需要一个外部符号 Add，请后续阶段填入地址"。
math.cc 编译时的情况刚好反过来：预处理展开后，编译器看到了 math.h 的声明和 Add 的函数体，它为 Add 生成机器码，产出的 math.o 中写入了 Add 的"已定义符号"记录，标注"此处提供 Add 的实体，谁需要可以来取"。
两个翻译单元在编译期完全独立，彼此不知道对方的存在。编译器处理 main.cc 时看不到 math.cc 里的函数体，处理 math.cc 时看不到 main.cc 里的调用点。这是 C++ 分离编译（separate compilation）模型的核心机制：每个源文件是一个独立的编译单位，编译器的语法检查、类型检查和代码生成全部限定在当前翻译单元的文本范围内。跨翻译单元的信息交换全部推迟到链接阶段，通过目标文件中的符号表来完成。
分离编译的直接工程收益是增量构建。修改 math.cc 中 Add 的实现后，只需重新编译 math.cc 这一个翻译单元，生成新的 math.o，再和未变化的 main.o 重新链接。main.cc 的翻译单元不需要重编，因为它的预处理输入（main.cc 加上它包含的所有头文件的内容）没有任何变化。在一个中型 C++ 项目里，源文件数量轻松到达几十上百个，全量编译可能要几分钟甚至十几分钟；增量编译只重编受影响的几个翻译单元，时间降到几秒。构建系统（Make、Ninja 等）的核心任务之一就是追踪每个翻译单元的输入依赖（源文件加上它通过 #include 直接和间接依赖的所有头文件），一旦某个输入文件发生变化，该翻译单元就需要重新编译。
以 Ninja 构建系统为例，开发者每次执行构建时，Ninja 会比较每个翻译单元的所有输入文件的时间戳或内容哈希，只对输入发生过变化的翻译单元调用编译器。CMake 的依赖扫描机制会自动为每个编译目标生成 .d 依赖文件，记录该翻译单元确切引用了哪些头文件（包括间接包含），使得依赖追踪精确到文件级别，避免因为一个未被实际包含的头文件变化而触发不必要的重编译。
反过来看，分离编译也决定了头文件改动的高昂代价。头文件本身不属于任何一个翻译单元，但它被 include 进多个翻译单元。改动一行头文件，每个 include 了它的翻译单元的预处理结果都会变化，导致所有相关翻译单元都需要重新编译。即使那些 .cc 文件的逻辑完全没有改动，只要预处理输入变了，编译器就必须重新处理整个翻译单元。在大型 C++ 项目中，避免在广泛包含的头文件中引入不必要的改动，是控制编译时间的一个几乎本能的工程习惯。有些团队甚至会统计每个头文件的"包含扇出"（fan-out），即有多少个翻译单元直接或间接地 include 了它，以此评估修改该头文件的编译代价。
编译器在翻译单元内部做的检查相当全面。语法错误（比如少了一个分号或者括号不匹配）、类型不匹配（比如把 std::string 传给接受 int 形参的函数）、缺少声明（比如用了一个从未声明过的标识符）、访问权限违规（比如在类外访问 private 成员）、模板实参推导失败，这些全都在单个翻译单元的范围内就能判定。编译器的诊断能力来自它对翻译单元内全部信息的完整掌握：所有类型定义、所有函数声明、所有模板定义、所有变量的声明，只要在当前翻译单元的文本中可见，编译器就能基于它们做出判断。
编译器管不到的那些问题，则会在链接阶段暴露。最典型的跨翻译单元问题有两类。第一类是声明与定义不一致。main.cc 的翻译单元和 math.cc 的翻译单元分别 include 了同一个 math.h，按理说它们对 Add 的签名应该达成共识。但如果有人直接绕过 math.h，在 main.cc 里手动写了 double Add(double, double); 这样的声明，同时在 math.cc 里仍然用 math.h 的 int Add(int, int) 定义，两个翻译单元各自编译都能通过（各自声明自洽），链接阶段却会因为符号名不匹配而失败。C++ 的函数重载依赖 name mangling 把参数类型编码进符号名，Add(int, int) 和 Add(double, double) 生成的符号名完全不同，链接器找不到匹配的符号，报 undefined reference。
第二类是遗漏定义。main.cc 的翻译单元里声明了 int Add(int, int)，编译器相信这个声明，让调用点通过了类型检查。但这个声明对应的函数体从未在任何翻译单元中被定义。编译器对这一情况毫不知情（它不跨翻译单元检查），链接器在遍历所有目标文件后发现了这个无处可落的未定义符号，报出另一个经典的 undefined reference。
理解这两类问题之后，可以做一个实验来加深直觉。故意只链接 main.o 而漏掉 math.o：
clang++ main.o -o app
链接器会输出 undefined reference to 'Add(int, int)' 并拒绝生成可执行文件。注意这个错误的措辞：它说的是"没找到对 Add 的引用对应的定义"，跟"没找到 Add 的声明"是两回事。编译阶段已经确认声明存在，链接阶段的报错指向的是缺失的实体。补上 math.o 后一切正常：
clang++ main.o math.o -o app
./app
# 输出：42
这两条命令的对比把分离编译模型的两个阶段呈现得非常清楚。编译期只验证接口合规性，链接期才验证实体完整性。这个两阶段模型是排查 C++ 多文件程序错误的基本心智框架。
头文件在这个模型中的角色是翻译单元之间的接口合约。math.h 里 int Add(int, int); 这一行声明，是 Add 函数对所有翻译单元做出的统一承诺。所有 include 了 math.h 的翻译单元都对 Add 的签名形成了同一个理解，编译器用这个理解来检查每个翻译单元内的调用点和定义点。如果多个翻译单元看到的声明不一致，C++ 标准将其归为 IFNDR（ill-formed, no diagnostic required），通俗说就是"程序不合法，但编译器不保证能检测出来"，实际工程中表现为难以追踪的链接错误或运行时异常。
一个容易漏掉的细节是：同一个头文件在不同的翻译单元里，展开后的实际内容可能不同。如果 math.h 的内容受到宏状态的影响（比如 #ifdef EXTENDED_MATH 条件下多声明了一个函数），而两个 .cc 分别在 include 它之前定义和不定义 EXTENDED_MATH，那么两个翻译单元看到的接口就不一致。编译器各自独立检查各自都能通过，链接阶段却可能因为一个 .o 期望的符号在另一个 .o 中不存在而出错。保持头文件自包含（self-contained）并且在 include 头文件之前不依赖特定的宏状态，是避免这类问题的基本原则。
翻译单元的边界还决定了符号的可见性。在 C++ 里，写在一个 .cc 文件中的普通函数和全局变量默认具有外部链接（external linkage），它们产生的符号对所有翻译单元可见，可以在链接阶段被其他目标文件引用。如果某个函数只在当前的 .cc 中使用，把它放进匿名命名空间（unnamed namespace）或者用 static 修饰，它的链接属性就变成内部链接（internal linkage）：符号只在当前翻译单元内部可见，不会暴露给链接器，其他翻译单元的同名符号与之完全无关。
内部链接机制在工程中的实际价值是避免符号冲突。假设两个不同的 .cc 文件里各有一个叫 Helper 的自由函数，各自完成完全不同的辅助工作。如果两个 Helper 都使用默认的外部链接，链接器会在两个目标文件中看到两个同名的外部可见符号，报 multiple definition 错误，即使这两个函数的实现完全不同。把 Helper 放进各自 .cc 的匿名命名空间中，两个 Helper 的符号分别限定在各自的翻译单元内，互不影响。这是 C++ 推荐的替代 C 风格 static 全局函数的方式。
匿名命名空间的机制背后是编译器偷偷给每个翻译单元的匿名命名空间分配一个唯一的内部名字，所以不同翻译单元里的匿名命名空间在符号层面是完全不同的命名空间，自然不会产生符号冲突。static 全局函数在 C 时代是标准做法，C++ 保留它仅为了兼容，新代码建议统一用匿名命名空间。另外，const 修饰的全局变量默认也是内部链接，这一点和普通全局变量不同。如果你在头文件里定义 const int kValue = 10;，每个 include 它的翻译单元各有一份独立的副本，不会触发 multiple definition，因为 const 全局变量默认带内部链接属性。
翻译单元的独立编译还有一个不太直观但很实用的推论：同一个翻译单元内的静态局部变量（在函数体内用 static 修饰的局部变量）和全局变量，其初始化顺序在同一个翻译单元内按照定义顺序执行，跨翻译单元则没有确定顺序。这个事实有时被称为"static initialization order fiasco"，是 C++ 中一个需要额外注意的工程陷阱。本系列不展开这个话题，但理解它的根因仍然在翻译单元的独立编译模型上：编译器无法在处理一个翻译单元时预先规划另一个翻译单元中全局对象的初始化时机。
翻译单元这个概念和模板编程有直接的因果关系。模板定义通常需要放在头文件中，原因不在模板的语言规则本身，而在编译器的翻译单元模型：编译器在实例化模板时需要看到完整的模板定义（不仅仅是声明），而编译器一次只处理一个翻译单元，它无法跨翻译单元去另一个 .cc 文件中寻找模板的定义体。反过来说，如果把模板定义放在 .cc 文件中，只有该 .cc 自己的翻译单元内部才能实例化那个模板，其他翻译单元只看到声明却看不到定义，实例化会失败。这是所有模板库（STL、Boost 等）大量使用 header-only 模式的技术根因。
模板的翻译单元行为还带来一个后续问题：同一个模板的同一组模板实参的实例化代码，可能在多个翻译单元的目标文件中各出现一份完全相同的代码。链接器需要能够识别并合并这些重复的实例化代码，这个过程叫"链接器去重"。这个现象同时说明了为什么 ODR 需要允许类定义、模板定义和内联函数定义进入多个翻译单元：如果不允许，header-only 的模板库根本无法工作。第 5 章会具体展开 ODR 的这些细节规则。
一个值得纠正的直觉是"源文件"和"翻译单元"的对应关系。日常交流中说"一个 .cc 是一个翻译单元"已经足够接近真相，但严格来说，翻译单元不包含被预处理指令丢弃的文本（比如 #ifdef 未命中分支中的代码），也不包含预处理指令本身。翻译单元指的是预处理之后的合成文本，而不是磁盘上的那个 .cc 文件。这个区分在实际排查中偶尔有用：当条件编译剪掉了你以为应该被编译器看到的代码时，预处理输出能帮你看到翻译单元的真实面貌。
翻译单元还解释了为什么很多 C++ 项目的增量编译会被一个小小的头文件改动拖慢。构建系统通常以翻译单元为最小重编译单位：某个 .cc 直接或间接依赖的头文件变了，这个 .cc 对应的翻译单元就需要重新生成并重新编译。一个底层公共头文件可能被几十个甚至几百个 .cc 间接包含，改动一行声明就会让一大片目标文件失效。把稳定接口放进头文件，把实现细节留在 .cc，本质上是在控制翻译单元之间的依赖传播范围。
回看整条编译链路，翻译单元是源码和编译器之间的桥梁。它把程序员组织在多个文件中的源码（.cc 和 .h 的分工）汇聚成编译器可消费的单一文本输入，同时把编译器的管辖权明确限定在这个单一文本的范围之内。编译器对翻译单元内的一切可以给出确定性的验证结论（语法正确、类型匹配、声明存在）；对翻译单元之外的一切，编译器只能选择信任声明，把实体查找推迟给链接器。
从翻译单元的角度审视工程决策，会自然得出几条原则。头文件的内容会被复制进每一个 include 它的翻译单元，因此头文件应当尽量精简，只放需要跨翻译单元共享的接口（函数声明、类型定义、模板定义），实现细节尽量放在 .cc 文件中。翻译单元之间的接口一致性依赖头文件来保证，因此头文件需要自包含，不依赖特定的 include 顺序或外部宏状态。改动头文件的代价比改动 .cc 高得多，因此在设计头文件时需要比 .cc 文件更谨慎地考虑稳定性和向后兼容性。
下一章把翻译单元内的编译器检查落实到一个更具体的语言层面：声明告诉编译器"有这个实体"，定义才真正提供这个实体。理解了翻译单元之后，声明和定义在不同翻译单元中分别扮演的角色就变得非常直观。多文件工程里的很多报错，本质上都在这条分界线上发生。把这条边界记住，后面看声明、定义和符号会顺很多，也会更稳。
阅读导航
