链接器抛出的multiple definition和undefined reference看着像两类错误其实是同一条规则的两面。这条规则叫 ODROne Definition Rule单一定义规则只有每个翻译单元对同一个实体有完全一致的理解「分开编译、最后链接」才可能成立。它也是最容易被跳过的一课因为违反它的第二种方式编译器不会给任何提示。1. 引子一行放错位置的定义头文件里写了一行看起来人畜无害的变量单文件编译一切正常文件一多就在链接阶段炸了。// header.h —— 反例不要这么写违反 ODR 第一层intg_config0;// 这是「定义」分配存储、可被修改不是「声明」原因不复杂头文件会被每个.cpp各自展开一份于是每个翻译单元translation unit简称 TU都提供了一份g_config的定义链接器把目标文件拼起来时看到同一个名字出现了两份「强定义」。a.cpp #include header.h ─┐ │ 预处理展开每个 TU 各拿到一份 g_config 的定义 b.cpp #include header.h ─┘ │ ▼ a.o: 符号 g_config定义 b.o: 符号 g_config定义 └──────────────┬───────────────┘ ▼ 链接器同名强符号出现两份无解 ▼ error: multiple definition of g_config下面用两个独立的翻译单元真跑一遍这个冲突a.cpp和b.cpp各自定义一次g_config再交给 CMake 链接成一个可执行文件。上一版这里受限于校验服务只能编译单个 TU没能复现跨 TU 的链接报错这次改用 Compiler Explorer 的多文件工程端点链接器原文就原样拿到了# CMakeLists.txt cmake_minimum_required(VERSION 3.20) project(dup CXX) set(CMAKE_CXX_STANDARD 17) add_executable(dup a.cpp b.cpp) // a.cpp int g_config 42; int fa(); int fa() { return g_config; } // b.cpp int g_config 7; // 第二份定义违反 ODR int fa(); int main() { return fa() g_config ? 0 : 1; }两个.cpp各自都能编译通过冲突只发生在链接阶段[ 33%] Building CXX object CMakeFiles/dup.dir/a.cpp.o [ 66%] Building CXX object CMakeFiles/dup.dir/b.cpp.o [100%] Linking CXX executable dup ld: CMakeFiles/dup.dir/b.cpp.o:(.data0x0): multiple definition of g_config; CMakeFiles/dup.dir/a.cpp.o:(.data0x0): first defined here collect2: error: ld returned 1 exit status说明ld前面的完整工具链路径已省略其余逐字未改。注意看前三行——两个.o都是Building成功、没有任何编译错误炸的是第三行的Linking。这正是「编译期能过、链接期才炸」的典型形态也是 ODR 第一层约束由链接器兜底的直接证据。把两个.cpp里的那两份定义合到一个 TU 里看编译器会立刻拦下链接器看到两份定义时本质就是这个冲突// 反例不要这么写同一个 TU 里出现两份定义片段编译不过intg_config1;intg_config2;prog.cc:2:5: error: redefinition of int g_config 2 | int g_config 2; | ^~~~~~~~ prog.cc:1:5: note: int g_config previously defined here 1 | int g_config 1; | ^~~~~~~~反过来只要「有声明、没定义」编译器照样放行问题留给链接器// 只声明不定义编译通过链接期报错片段#includecstdioexternintg_config;// 声明不分配存储intreadConfig(){returng_config;}// 用它但全程序没有那份定义/usr/bin/ld: /tmp/ccUD5U7t.o: in function main: prog.cc:(.text.startup0x6): undefined reference to g_config collect2: error: ld returned 1 exit status/tmp/ccXXXXXX.o里的临时文件名每次编译都不同报错格式才是重点。官方文档Definitions and ODR — cppreferenceODR 的正式定义与例外清单就在这一页。2. ODR 的两层含义ODR 由两条独立约束组成很多「ODR 问题」讲不清就是把两层混在一起谈。层次约束内容违反后谁报错症状第一层一份定义整个程序里每个非inline的变量 / 函数只能有一份定义类、模板、枚举等类型在每个 TU 内最多一份定义链接器能看到multiple definition构建直接失败反而安全第二层逐 token 相同同一个实体出现在多个 TU 时各处的定义必须逐 token 相同且名字查找结果一致没有人报错→ 行为未定义undefined behavior链接成功、运行结果错乱最难查第一层的后果是可见的第二层才阴险所有 TU 都编译过了、链接也过了只有一个 TU 认为Config是 4 字节、另一个认为是 16 字节各自按自己的理解读写同一块内存。「定义」和「声明」的区别是理解第一层的前提声明只是告诉编译器「有这么个东西」定义才把实体造出来。下面这段程序故意把两者分开写#includecstdio// 声明告诉编译器「有这个东西定义在别的 TU」externintg_config;externintreadConfig();// 定义本 TU 提供实体真实项目里这两行在 config.cppintg_config7;intreadConfig(){returng_config*2;}intmain(){printf(g_config %d\n,g_config);printf(readConfig() %d\n,readConfig());}g_config 7 readConfig() 14官方文档Storage duration and linkage — cppreference区分extern/static/ 内部链接 / 外部链接的权威表格。3. 为什么非得有 ODR编译模型决定的每个 TU 是独立编译的编译器处理a.cpp时对b.cpp一无所知而很多决策必须在编译期定死sizeof(Config)、成员偏移、inline函数体展开、模板实例生成。它们都建立在一个假设上别的 TU 对同一个实体的理解跟我完全一样。a.cpp b.cpp 各自独立编译 ┌──────────┐ ┌──────────┐ │ 预处理 │ │ 预处理 │ 头文件被各自展开一份互不知情 ├──────────┤ ├──────────┤ │ 编译 │ │ 编译 │ 这里定死sizeof、成员偏移、 ├──────────┤ ├──────────┤ inline 函数体、模板实例地址 │ a.o │ │ b.o │ .symtab我提供哪些符号 / 我需要哪些 └────┬─────┘ └─────┬─────┘ └───────────┬──────────────────┘ ▼ ┌─────────┐ │ 链接器 │ 只做两件事给同名符号配一个地址、填重定位 └────┬────┘ 不做任何布局一致性检查 ▼ 可执行文件链接器只「按名字匹配」不知道a.o和b.o里的Config布局是否一致它连这是个类都不知道。所以 ODR 是作者与编译器之间的契约你保证各 TU 定义一样编译器才敢把布局和内联结果提前定死这份信任换来独立编译与增量构建的效率代价是第二层违约时没人替你报警。官方文档Translation phases — cppreferenceTU 是怎么从源文件一步步变成待链接单元的。4. ODR 的例外哪些定义可以出现在多个 TU 里ODR 不是「一律禁止重复定义」有一批实体天然要写在头文件里、被多个 TU 各包含一份。它们的共同要求是各处的定义必须逐 token 相同。实体能否在多个 TU 里出现定义条件 / 说明普通函数、普通全局变量不能只能在一个.cpp里定义一份inline函数能各 TU 定义必须逐 token 相同链接器留一份inline变量C17能同上变量也享受这条豁免类 /struct/union定义能用到的每个 TU 里都得有完整且相同的定义类内定义的成员函数隐式inline模板函数模板、类模板及其成员能实例化结果在各 TU 必须相同constexpr函数能C11 起constexpr函数隐含inline枚举、typedef、using别名能属于类型定义同上匿名命名空间 /static实体能但各 TU 是不同实体内部链接不参与同名合并因此不受 ODR 约束inline那一行的实际含义用一个例子最直观头文件里放inline变量多个「TU」这里用两个函数模拟拿到的是同一块内存#includecstdio// 头文件里写 inline 变量全程序只有一份定义ODR 例外inlineintg_shared0;intunitA(){returng_shared;}// 假装这个函数定义在 a.cppintunitB(){returng_shared;}// 假装这个函数定义在 b.cppintmain(){unitA()5;printf(unitA 写入后unitB 读到 %d\n,unitB());printf(两个函数拿到同一块内存 %d\n,(int)(unitA()unitB()));}unitA 写入后unitB 读到 5 两个函数拿到同一块内存 1inline变量与inline函数解决的是同一个问题让「有必要写在头文件里的定义」不再触发multiple definition变量这条豁免到 C17 才有。官方文档inline specifier — cppreferenceinline的语义就是「允许在多个 TU 定义链接器留一份」。5. 违规场景二宏让不同 TU 看到不同版本最阴险第二层约束被违反最典型的成因不是手滑写错而是同一个头文件在不同 TU 里被宏展开成了不同内容。下面用两个结构体模拟「A 侧没开附加宏、B 侧开了」的两种展开结果#includecstdio#includecstddef// 同一个「头文件」因宏不同被展开成两个版本// TU A 看到 CfgATU B 看到 CfgB —— 而 ODR 要求各 TU 的类定义逐 token 相同structCfgA{intid;};structCfgB{intid;doubleratio;};intmain(){printf(TU A 眼里的 sizeof(Cfg) %zu\n,sizeof(CfgA));printf(TU B 眼里的 sizeof(Cfg) %zu\n,sizeof(CfgB));printf(A 按自己布局推算的下一字段偏移 %zu\n,sizeof(int));printf(B 里 ratio 的真实偏移 %zu\n,offsetof(CfgB,ratio));}TU A 眼里的 sizeof(Cfg) 4 TU B 眼里的 sizeof(Cfg) 16 A 按自己布局推算的下一字段偏移 4 B 里 ratio 的真实偏移 8A 侧认为对象只有 4 字节、下一字段从偏移 4 开始B 侧实际从偏移 8 开始。于是A 侧按自己的布局去读 B 侧传过来的对象会把 B 的填充字节当成数据——脏读A 侧按 4 字节分配 / 释放或memcpy这个对象直接踩坏堆。这类代码编译器不报错、链接器不报错只在特定调用路径上表现异常。常见成因头文件里的#ifdef开关NDEBUG、平台宏同一路径下装着两个版本的头文件#include搜索顺序不同一个宏同时改了类定义和inline函数的实现体。修法只有一个方向让同一个实体的定义在所有 TU 里逐 token 相同去掉影响布局的宏开关或保证构建系统给所有 TU 传一致的宏统一加-D。官方文档C Core GuidelinesSF.2「头文件必须自洽」与 SF.22「内部实体放匿名命名空间」是本节修法的规范出处。6. 违规场景三头文件里的全局const反直觉直觉上const更安全所以很多人会在头文件里写const int kLimit 512;。它不报错但行为跟你想的不一样命名空间作用域的const变量默认是内部链接internal linkage相当于自动加了static头文件被 10 个 TU 包含内存里就有 10 份kLimit地址各不相同。#includecstdio// 想在头文件里放「全程序共享一份」的常量C17 用 inlineconstexpr 隐含 inlineinlineconstexprintkMaxConn1024;// 文件作用域的 const 默认是内部链接每个包含它的 TU 各拿一份自己的副本constintkFileLocal512;constint*readMax(){returnkMaxConn;}intmain(){printf(kMaxConn %d\n,kMaxConn);printf(kFileLocal %d\n,kFileLocal);printf(两次取址拿到同一份 %d\n,(int)(readMax()kMaxConn));}kMaxConn 1024 kFileLocal 512 两次取址拿到同一份 1「每个 TU 各有一份」在单个 TU 里观测不到但它在真实项目里有两种典型表现跨 TU 用extern const int kLimit;引用它会报undefined reference内部链接不导出符号每个 TU 各自初始化「这边改了那边没生效」很多玄学 bug 的来源。只读常量各占一份问题不大真正会出事的是带动态初始化的const对象const std::string kPrefix makePrefix();写在头文件里每个 TU 各跑一遍初始化跨 TU 顺序还不确定静态初始化顺序问题SIOF。修法常量用inline constexpr运行期共享状态用extern声明 单个.cpp定义。官方文档const — cppreference明确写出命名空间作用域const默认内部链接这条反直觉规则。7. 常见误解匿名命名空间里的东西不是「同一份」匿名命名空间unnamed namespace和static一样给出内部链接所以两个 TU 里各自的helper()是两个互不相干的实体这不是违反 ODR而是压根不参与 ODR 的合并常被误解成「匿名命名空间里的函数全局唯一」。#includecstdionamespace{// 匿名命名空间本 TU 私有内部链接类型、常量、函数都能放structImpl{intv;};constexprintkSeed7;intstep(intx){returnxkSeed;}}// namespacestaticintlegacyStep(intx){returnx*3;}// static同样内部链接但只能修饰函数/变量intmain(){constImpl impl{5};printf(匿名命名空间里的类型可实例化 sizeof(Impl) %zu\n,sizeof(Impl));printf(匿名命名空间里的函数 step(5) %d\n,step(impl.v));printf(static 函数 legacyStep(5) %d\n,legacyStep(5));}匿名命名空间里的类型可实例化 sizeof(Impl) 4 匿名命名空间里的函数 step(5) 12 static 函数 legacyStep(5) 15匿名命名空间 vsstatic现代 C 该选哪个维度文件作用域static匿名命名空间能修饰什么只有函数、变量函数、变量、类型类 / 枚举 / 模板、常量链接属性内部链接内部链接跨 TU 是否同一实体否各 TU 一份否各 TU 一份类型能否也私有化不能static修饰类无意义能类定义不导出符号天然不与别的 TU 撞名推荐度历史写法现代 C 首选为什么优先匿名命名空间它把「内部」表达得更完整。static只管名字可见性管不了类型两个 TU 各定义一个同名但结构不同的struct Helper就是实打实的 ODR 违规第二层放进各自的匿名命名空间就没这个问题。这正是 Core Guidelines SF.22 的建议。8. 头文件里想放一个变量到底怎么写判断标准只有两个要全程序一份还是每 TU 一份要不要可变。写法链接属性全程序几份适用场景代价 / 坑头文件里int g_config 0;外部链接每 TU 一份定义无写法错误直接multiple definition头文件里extern int g_config; 某个.cpp里定义外部链接一份默认选择共享的可变状态多写一行定义容易忘头文件里inline int g_config 0;C17外部链接一份想让头文件自洽、配置表 / 常量表需 C17初始化仍是动态初始化头文件里static int g_config 0;内部链接每 TU 一份副本只在本 TU 用跨 TU 不共享改了别处看不到头文件里inline constexpr int kMax 1024;外部链接一份编译期常量最优不可改且不能是运行期算出来的值结论共享可变状态用extern声明 单点定义共享常量用inline constexpr本 TU 私有实现放匿名命名空间。头文件里的裸const和static都不是「共享」的正确表达。9. 完整示例一个「头文件友好」的写法把这篇要点串成一个可编译的程序inline constexpr常量、类内隐式inline的成员函数、只在本 TU 使用的匿名命名空间实现细节。#includecstdio#includestring#includevector// —— 一个「头文件友好」的写法示范 ——inlineconstexprconstchar*kAppNameodr-demo;// C17 inline 变量多 TU 包含不冲突structConfig{std::string name{kAppName};intmax_conn{1024};// 类内定义的成员函数隐式 inline可以安全写在头文件里std::stringdescribe()const{returnname (max_connstd::to_string(max_conn));}};namespace{// 只在本 TU 使用的实现细节匿名命名空间std::stringnormalize(std::string s){for(charch:s){if(ch )ch-;}returns;}}// namespaceintmain(){constConfig cfg{odr demo,2048};conststd::vectorstd::stringtags{normalize(cfg.name),normalize(max conn)};printf(Config::describe() %s\n,cfg.describe().c_str());printf(归一化后的标签 %s / %s\n,tags[0].c_str(),tags[1].c_str());}Config::describe() odr demo (max_conn2048) 归一化后的标签 odr-demo / max-conn这几行写进头文件也不会出问题kAppName是inline变量、Config是类定义、describe()是类内定义的成员函数隐式inline、normalize()在匿名命名空间里对外不可见。10. 延伸阅读Definitions and ODR — cppreferenceODR 原文定义与例外清单这篇第 2、4 节的依据。Storage duration and linkage — cppreferenceextern/static/ 内部链接 / 外部链接对照表理清第 6 节那条反直觉规则。C Core GuidelinesSF.2头文件自洽、SF.22内部实体放匿名命名空间的实操建议。本知识库内的相关篇目《命名空间与代码组织匿名命名空间、ADL 与 using 的边界》 —— 命名空间不只是「给名字加前缀」它同时管三件事《头文件组织与前置声明编译依赖管理》 —— #include 的本质是文本替换一个被 N 个 .cpp 包含的头文件改一次就要重编 N 个文件。《CMake 入门从单文件到多目标工程》 —— 现代 CMake 的核心是以 target 为中心11. 一句话总结两层要分开记第一层「整个程序一份定义」违反时链接器会拦下multiple definition第二层「各 TU 定义逐 token 相同」违反时没人报错、是静默 UB。修法记四条头文件里只放声明、共享常量用inline constexpr、共享状态用extern 单点定义、本 TU 内部实现放匿名命名空间。