前言C 的编译模型和大多数人的直觉不一样编译器每次只看到一个翻译单元translation unitTU也就是一个 .cpp 文件连同它包含的所有头文件展开后的结果。它完全不知道别的 .cpp 里写了什么两边的联系全靠链接器在最后一步用符号symbol对接起来。多文件编程里的绝大多数报错根源都在这个编译期彼此看不见、链接期才见面的模型上。最常见的两个误解第一个是把声明declaration和定义definition当成一回事。声明是我保证有这么个东西定义是这就是它的实体。一个函数可以在很多个 .cpp 里被声明但整个程序里只能被定义一次——这条规则叫ODROne Definition Rule单一定义规则。违反它的后果就是链接期那句让人摸不着头脑的multiple definition of ...或者 MSVC 的LNK2005。第二个误解是把#include当成导入模块。它不是。#include是文本替换预处理器把头文件内容原样粘进当前位置。所以头文件里每多一行可执行的定义每个包含它的 .cpp 就多一份。本文以 C17 为基准用一个三文件的小工程把编译、链接、链接性、名字修饰这几件事讲清楚代码在 GCC 13 / Clang 17 / MSVC 19.3x 上均可编译。一、声明、定义与链接性在文件作用域里同一个名字可以有外部链接external linkage、内部链接internal linkage或无链接。这决定了链接器会不会把它暴露给别的翻译单元。写法是声明还是定义链接性int add(int, int);声明外部int add(int a, int b) { return a b; }定义外部extern int g_count;声明外部int g_count 0;定义外部static int helper() { ... }定义内部namespace { int helper() { ... } }定义内部const int kMax 10;命名空间作用域定义内部inline int f() { ... }定义外部允许在多个 TU 中出现同一份定义inline constexpr int kMax 10;C17定义外部全程序唯一这里有两个 C 和 C 的关键差别务必分清在C里文件作用域的const int kMax 10;是外部链接的在C里它是内部链接。所以 C 里把const常量写进头文件每个 TU 各拿一份拷贝既不报重复定义也会让不同 TU 里kMax的地址不同。在C里函数内不能定义函数C 里 class 定义可以放进头文件因为在类体内定义的成员函数是隐式inline的。C17 新增了inline 变量这才让在头文件里定义一个真正的全局变量变成可能inline修饰的变量在全程序里是同一个实体多个 TU 都能看到同一份定义而不违反 ODR。二、一个最小可编译的三文件工程下面这个工程把该注意的点都放进去了函数声明与定义分离、类定义在头文件、模板定义在头文件、C17 inline 变量。math_utils.h#ifndef MATH_UTILS_H #define MATH_UTILS_H #include string // 声明定义在 math_utils.cpp 里 int add(int a, int b); // 类定义放在头文件类体内定义的成员函数是隐式 inline不会重复定义 class Accumulator { public: explicit Accumulator(int init 0) : sum_(init) {} void add(int v) { sum_ v; } int sum() const { return sum_; } private: int sum_; }; // C17 inline 变量头文件里定义全程序只有一份 inline constexpr int kMaxItems 128; // 函数模板的定义必须对使用点可见所以只能放头文件 template class T T twice(T v) { return v v; } #endif // MATH_UTILS_Hmath_utils.cpp#include math_utils.h // 这里才是 add 的唯一一份定义 int add(int a, int b) { return a b; }main.cpp#include math_utils.h #include iostream #include string int main() { Accumulator acc(10); acc.add(kMaxItems); std::cout add(acc.sum(), 1) \n; // 139 std::cout twice(std::string(ab)) \n; // abab 后换行 return 0; }编译分两种方式。一次性编译g -stdc17 -Wall -Wextra -pedantic math_utils.cpp main.cpp -o app分步编译更接近真实工程便于只重编改动的文件g -stdc17 -c math_utils.cpp -o math_utils.o g -stdc17 -c main.cpp -o main.o g math_utils.o main.o -o app如果用的是 CMake等价的最小配置是cmake_minimum_required(VERSION 3.16) project(demo CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) add_executable(app math_utils.cpp main.cpp)三、链接期报错怎么读多文件编程里 90% 的困惑来自身链接器的两类消息。它们的含义完全相反报错含义常见原因undefined reference to add(int, int)GCC/Clang/LNK2019MSVC有人用了这个符号但没人定义忘了把 .cpp 加进编译只写了声明模板定义被放进了 .cppmultiple definition of add(int, int)GCC/Clang/LNK2005MSVC同一个符号被定义了不止一次把非 inline 的函数定义或全局变量定义写进了头文件GCC 的报错里会带上两个文件名告诉你这两个定义分别来自哪个目标文件MSVC 的LNK2005则会顺带给出already defined in ...的行。看到undefined reference的第一反应应该是这个符号的定义在哪个 .o 里而不是去改头文件。模板是undefined reference的一个高频陷阱原因和上面说的编译模型直接相关编译器在实例化点必须看到模板的定义。如果你把模板定义放进impl.cpp而在main.cpp里调用它main.cpp这个 TU 里只有声明编译器认为实例化留给别处链接时又找不到于是报undefined reference。三种解法把模板定义放回头文件最常用。在impl.cpp里做显式实例化template std::string twicestd::string(std::string);这样该 TU 里就会真的产生这个符号。在头文件里用extern templateC11 起告诉其他 TU别在本 TU 实例化去别处找以缩短编译时间。四、名字修饰与 C 互调C 和 C 编译出的符号名不一样原因是C 支持重载add(int,int)和add(double,double)必须能共存所以编译器要把参数类型编码进符号名这就是名字修饰name mangling。C 没有重载符号名就是函数名本身。在 Linux 上用 Itanium ABIGCC / Clang 在 Linux 上遵循的 C ABI时int add(int, int)修饰后的符号名是_Z3addii_Z是前缀3add是长度为 3 的名字 addii是两个int参数。MSVC 用的是另一套修饰规则名字会长得多。用nm -C就能看到目标文件里的符号-C表示按 C 规则反修饰成可读形式g -stdc17 -c math_utils.cpp -o math_utils.o nm -C math_utils.o | grep -i add一个提供 C 接口的头文件应当是这么写的/* c_abi.h —— 既能被 C 编译也能被 C 编译 */ #ifndef C_ABI_H #define C_ABI_H #ifdef __cplusplus extern C { #endif int c_add(int a, int b); /* 实现在一个 .c 文件里 */ #ifdef __cplusplus } #endif #endif /* C_ABI_H */extern C的作用只有一个关掉名字修饰并采用 C 的调用约定。它不会把 C 变成 C函数体里照样可以写 C。需要注意两点extern C里的函数不能重载重载会撞名也不能直接套在模板上extern C只影响链接规范不影响类型系统所以头文件里还得配#ifdef __cplusplus让它对 C 编译器也合法——因为extern C这个写法本身在 C 里根本不存在。反过来C 代码调 C 时常见做法是提供一个extern C的薄封装层在 .cpp 里实现头文件用上面的条件编译暴露给 C 侧。常见坑点场景❌ 错误写法✅ 正确写法说明头文件里放函数定义头文件里直接写int add(int a,int b){return ab;}只留声明定义放 .cpp确需放头文件就标inline被两个 .cpp 包含就是multiple definition头文件里放全局变量int g_count 0;写在头文件extern int g_count;加一处定义或 C17inline int g_count 0;前者每个 TU 一份链接期冲突模板定义分离模板定义写进 .cpp头文件只有声明模板定义放头文件或在 .cpp 里显式实例化实例化点看不到定义就是undefined reference头文件被重复包含头文件没有 include guard#ifndef/#define/#endif或#pragma once类、结构体被重复定义会直接编译失败循环包含a.h 包含 b.hb.h 又包含 a.h一处改成前向声明class B;需要用到成员时在 .cpp 里再包含前向声明只能用于指针、引用和参数类型默认参数写两遍声明和定义里都写 0只在声明处写一次GCC 会报 default argument given for parameter after previous specification依赖传递包含main.cpp 用了std::vector却不包含vector靠别的头文件带进来谁用谁包含哪天头文件改了包含关系代码就突然编不过头文件里using namespace头文件顶层写using namespace std;在 .cpp 里写或只using std::string;污染会扩散到所有包含者重载决议可能被改变关于#pragma once它不是 ISO C 标准的一部分但 GCC、Clang、MSVC 都支持。可移植性要求高时用标准 include guard 更稳妥#pragma once的好处是不用费心给宏起不重名的名字而且编译器可以在文件级做去重避免打开文件的开销。总结概念要点翻译单元一个 .cpp 加上它展开后的所有头文件编译器只看得到这一个声明与定义声明可以有很多份定义在整个程序里只有一份ODR链接性文件作用域的static和匿名命名空间是内部链接C 里const常量默认也是内部链接inline函数和 C17 起的变量允许多个 TU 持有同一份定义模板定义必须对使用点可见否则链接期undefined referenceextern C关掉名字修饰用于 C 与 C 互调本质是链接规范问题多文件编程不需要背很多规则抓住一句话就够了编译期每个翻译单元是孤岛链接期靠符号把孤岛连起来。凡是编译器怎么看不到的困惑答案通常是它在另一个 TU 里凡是重复定义的困惑答案通常是这段定义被预处理器复制了多份。