头文件里定义static变量，为什么每个文件会各有一份？

从第一次在头文件里写 static int counter = 0; 开始，我就隐约觉得哪里不对劲：头文件明明被好几个 .c 文件 #include 了，但编译链接一点错都不报；可运行起来之后，这个 counter 的状态就像“分身”一样，各改各的。后来我用 gcc -E 看预处理输出、用 nm 翻符号表、再打印运行时的地址，才彻底想明白——static 和 #include 之间的相互作用，本质上就是“文本复制”和“翻译单元隔离”这两件事叠加的结果。这篇实验报告就把当时搭的最小复现环境、对比实验和踩坑结论完整记录下来，适合所有正在用 C 语言做多文件工程、或者对“头文件里到底能不能定义 static 变量”心存疑惑的开发者。

1. 一个反直觉的起点：#include 把代码“原样粘贴”而非“引用进符号表”

1.1 预处理输出里的真相

很多初学者（包括当年的我）会把 #include 理解成类似 Java import、Python import 的机制——好像头文件里写的东西被“引用”进当前文件，用到了才去解析。但实际上 C 语言的 #include 只是一个文本替换指令，发生在编译的最早阶段（预处理阶段），机制上简单粗暴：把被包含文件的全部内容，逐字复制到 #include 语句所在的位置。

我们做一个最小验证。假设我有两个文件：

c复制// shared.h
#ifndef SHARED_H
#define SHARED_H

int add(int a, int b) {
    return a + b;
}

#endif

c复制// main.c
#include "shared.h"

int main(void) {
    return add(1, 2);
}

对 main.c 执行预处理，不进行实际编译：

bash复制gcc -E main.c -o main.i

打开生成的 main.i，你会看到原来的 #include "shared.h" 那一行已经不在了，取而代之的是一整段从 shared.h 里复制进来的代码：

c复制# 1 "main.c"
# 1 "shared.h"
# 1 "<built-in>"
# 1 "<command-line>"

#ifndef SHARED_H
#define SHARED_H

int add(int a, int b) {
    return a + b;
}

#endif

# 1 "main.c"
int main(void) {
    return add(1, 2);
}

注意，add 函数的定义是完整“贴”进来的。这不是“引入一个符号引用”，而是把函数实现、变量定义全部变成了当前文件的一部分。

1.2 “文本复制”这个性质，决定了后面的一切

把 #include 理解成文本复制之后，一个关键的推论自然出现了：每一个包含某头文件的 .c 文件，都会在各自独立的预处理过程中，得到一份完全独立的头文件代码副本。也就是说：

• main.c 预处理后，有一份 shared.h 的代码；
• unit_a.c 预处理后，也有一份一模一样的 shared.h 代码；
• unit_b.c 预处理后，还有一份一模一样的 shared.h 代码。

这三份代码虽然内容相同，但它们已经分别属于三个不同的“翻译单元”（translation unit）。翻译单元可以粗略理解为“一个 .c 文件经过预处理展开后的完整源码”。后续编译、符号解析、链接，都是以翻译单元为单位进行的。

所以，如果你在头文件里写了一个 static 变量，那么“static”这个关键字施加的作用范围，不是“整个工程”，而是“当前这一个翻译单元”。头文件被多少个 .c 文件包含，这个 static 变量就会同时在多少个翻译单元里被定义一份。至于为什么这些同名定义不会互相冲突，那是链接器层面的问题，后面单独用一节来讲。

2. static 的三种面孔：局部变量、文件级变量，以及链接性差异

2.1 函数内部的 static：改变存储期，不改变作用域

先看最常见的一种：

c复制int next_id(void) {
    static int id = 0;
    return id++;
}

这里的 static 改变的是变量 id 的存储期（storage duration）。原本一个局部变量在函数调用结束后生命周期就结束；加上 static 后，它被放到静态存储区，生命周期延长到整个程序运行期间，但它的作用域依然是 next_id 函数内部。外部代码无法通过名字访问它，也没法通过链接器符号引用它。

这类 static 变量和 #include 的相互作用相对温和，只有一种情况需要特别警惕：如果你在头文件里定义了一个 static inline 函数，而这个函数内部又有一个 static 局部变量，那么每个包含这个头文件的翻译单元，都会各自拥有一份独立函数和独立局部变量。后文对比实验里会展示这个场景。

2.2 文件作用域的 static：改变链接性，让符号“只属于当前翻译单元”

当一个 static 关键字用在函数外面、修饰全局变量或函数时，它的作用是改变该符号的链接性（linkage）。默认情况下，一个全局变量的链接性是外部链接（external linkage），意思是整个程序里所有翻译单元都可以通过 extern 声明来访问它。一旦加了 static，它的链接性就变成内部链接（internal linkage），意思是它只能被当前翻译单元中的代码访问，其他翻译单元根本看不到它。

函数同理：

c复制static void internal_helper(void) {
    // 只在当前 .c 文件里可见
}

internal_helper 不会导出到全局符号表，其他 .c 文件即使用 extern 声明也无法调用。

2.3 三种情况对比

所以，static 和 #include 相遇时，真正起决定性作用的是“内部链接”。当 static 变量出现在头文件里，而头文件又被多个 .c 包含时，每个翻译单元都会产生一个具有内部链接的同名变量。它们看起来是同一个名字，实际上是互不相干的一堆独立对象。

3. 主实验：同一个头文件里的 static 变量，在不同 .c 文件中有几份？

3.1 实验设计

为了把现象彻底暴露出来，我设计了四个文件：

c复制// shared.h
#ifndef SHARED_H
#define SHARED_H

#include <stdio.h>

static int counter = 0;

void init_counter(void);
int *get_counter_a(void);
int *get_counter_b(void);

#endif

c复制// unit_a.c
#include "shared.h"

void init_counter(void) {
    counter = 100;
}

int *get_counter_a(void) {
    return &counter;
}

c复制// unit_b.c
#include "shared.h"

int *get_counter_b(void) {
    return &counter;
}

c复制// main.c
#include "shared.h"

int main(void) {
    int *addr_a = get_counter_a();
    int *addr_b = get_counter_b();

    printf("addr_a = %p\n", (void *)addr_a);
    printf("addr_b = %p\n", (void *)addr_b);

    init_counter();

    printf("after init_counter: *get_counter_a() = %d\n", *get_counter_a());
    printf("after init_counter: *get_counter_b() = %d\n", *get_counter_b());

    return 0;
}

编译：

bash复制gcc -c unit_a.c -o unit_a.o
gcc -c unit_b.c -o unit_b.o
gcc -c main.c -o main.o
gcc unit_a.o unit_b.o main.o -o demo
./demo

3.2 运行结果：地址不同，状态互不干扰

我这边实测输出类似这样（具体地址每次运行可能不同）：

text复制addr_a = 0x55e9b0c2a018
addr_b = 0x55e9b0c2a01c
after init_counter: *get_counter_a() = 100
after init_counter: *get_counter_b() = 0

两个关键结论：

1. get_counter_a() 和 get_counter_b() 返回的地址不一样，说明 unit_a.c 里的 counter 和 unit_b.c 里的 counter 是两个不同的对象。
2. init_counter() 把 unit_a.c 里的 counter 改成了 100，但 unit_b.c 里的 counter 仍然是 0，说明它们的状态完全不共享。

从业务视角看，这就像同一个头文件里的同一个“全局变量”，到了不同 .c 文件里各自变成了“私有副本”。对写业务逻辑的人来说，这是最容易产生诡异 bug 的地方。

3.3 用 nm 看符号表：小写 b 代表局部符号

再把 unit_a.o 和 unit_b.o 的符号表翻开：

bash复制nm unit_a.o

输出片段：

text复制0000000000000000 b counter
0000000000000000 T get_counter_a
0000000000000000 T init_counter
0000000000000000 T get_counter_b

注意 counter 前面的符号类型是 b（小写），含义是 BSS 段内的局部符号（局部未初始化数据）。在 nm 输出中，小写字母代表 local 符号，大写字母代表 global 符号。get_counter_a、init_counter 这些函数是 T（大写），说明它们会导出到全局符号表，可以被其他目标文件链接；而 counter 是 b，链接器看到它时知道这是个局部符号，不会让它参与跨目标文件的符号匹配。

再看 nm unit_b.o，里面同样有一个 counter，同样是 b。两个目标文件里各有一个名为 counter 的局部符号，但互不冲突，链接器也不会抱怨“重复定义”。这正是 static 内部链接在目标文件层面的真实体现。

4. 对比实验：同一行代码，换几种写法，命运完全不同

4.1 去掉 static：立刻出现 multiple definition 链接错误

把 shared.h 里的：

c复制static int counter = 0;

改成：

c复制int counter = 0;

其他代码完全不变，重新编译到链接阶段，会得到：

text复制/usr/bin/ld: unit_a.o:(.data+0x0): multiple definition of `counter'; main.o:(.data+0x0): first defined here
/usr/bin/ld: unit_b.o:(.data+0x0): multiple definition of `counter'; main.o:(.data+0x0): first defined here
collect2: error: ld returned 1 exit status

原因很直接：去掉 static 后，counter 的链接性变为外部链接。main.o、unit_a.o、unit_b.o 三个目标文件里都定义了一个名为 counter 的全局强符号，链接器无法决定到底用哪一个，只能报错。

这个现象其实也反过来说明：static 加的并不是“防重复定义”的魔法，而是把符号从“全工程共享”降级成了“当前翻译单元私有”，从而绕开了符号冲突。

4.2 换成 extern：跨文件共享一份数据

把 shared.h 改成：

c复制extern int counter;

同时在 unit_a.c 里定义：

c复制int counter = 0;

编译链接运行：

text复制addr_a = 0x55e9b0c2a018
addr_b = 0x55e9b0c2a018
after init_counter: *get_counter_a() = 100
after init_counter: *get_counter_b() = 100

地址相同，状态共享。extern 声明不分配存储空间，只告诉编译器“这个符号在某个翻译单元里定义，到时候链接器帮我找到它”。这是 C 语言实现跨文件共享全局变量的标准姿势。注意，定义只能放在一个 .c 文件里，否则又回到 4.1 的多重定义问题。

4.3 换成 const 或 static const：C 语言与 C++ 的差别

把 shared.h 改成：

c复制const int kCounter = 0;

在 C 语言里，const 并不改变链接性，它默认仍然是外部链接。多个 .c 文件各自包含这个定义后，链接阶段会再次出现 multiple definition of 'kCounter' 的错误（具体表现取决于编译器和优化级别，但概念上属于违规）。因此，C 语言中如果头文件需要定义只读常量，通常写成：

c复制static const int kCounter = 0;

或者用 enum、#define。加上 static 后，每个翻译单元各持有一份只读副本，互不干扰，也不会链接冲突。

在 C++ 中情况有所不同：const 变量默认具有内部链接，所以 const int kCounter = 0; 写在头文件里可以被多个翻译单元包含而不报错，每个翻译单元仍会获得一份独立副本（实际优化后往往合并到只读段或直接替换成立即数）。这篇文章的实验环境是 C 语言，所以下面的表格按 C 语言语义整理。

4.4 static inline 函数：每个编译单元各有一份实现

如果头文件里定义的是：

c复制static inline int max_int(int a, int b) {
    return a > b ? a : b;
}

每个包含该头文件的翻译单元都会拥有自己的 max_int 内部实现，编译器通常会在调用处直接展开，不产生跨文件符号。这是一种安全的头文件实现方式，也是 C 语言里在头文件提供小工具函数的推荐做法。

但有一个容易忽略的坑：如果这个 static inline 函数内部定义了 static 局部变量，那么每个翻译单元会各自维护一份独立的局部变量副本。例如：

c复制static inline int get_count(void) {
    static int count = 0;
    return count++;
}

a.c 里调用三次 get_count()，得到 0、1、2；b.c 里再调用三次，同样从 0 开始，而不是从 3 开始。这与本文主实验的现象同源，都是“头文件被复制到多个翻译单元”造成的。

5. 链接器视角：为什么同名 static 符号不会“撞车”

5.1 从目标文件符号表看内部链接

C 语言构建过程可以粗略拆成两步：编译和链接。

编译期，每个 .c 文件被单独编译成一个 .o 目标文件。编译这个 .c 文件时，编译器只关心当前翻译单元里有什么，不关心其他 .c 文件。此时，static 变量在目标文件符号表中被标记为 local 符号。

链接期，链接器把多个 .o 文件合并成可执行文件。它需要解析每个目标文件对外部符号的引用，并检查全局符号是否有冲突。链接器在解析符号时，只关心 global 符号；带 static 的 local 符号对链接器来说属于“本目标文件的内部事务”，不会参与跨目标文件的匹配。

所以，两个 .o 文件里都定义了一个名叫 counter 的 local 符号，链接器认为这完全合法。就像两栋楼内部都有自己的“001 房间”，只要它们不对外宣称自己是“某统一编号”，物业（链接器）就不会认为冲突。

5.2 多个副本并不免费：内存、初始化、维护成本

虽然链接不会报错，但多个副本是有代价的：

• 每个翻译单元都会分配自己的存储空间。如果 static 变量是一个大数组，比如 static int cache[1024] = {0};，头文件被 20 个 .c 文件包含，就可能产生 20 份 4KB 的缓存副本，内存开销直接翻 20 倍。
• 每个翻译单元里的 static 变量通常在程序启动时执行初始化（部分编译器将其放到 .data 段或通过启动代码进行零初始化等）。如果初始化逻辑里调用了函数，那么每个翻译单元都会执行一遍，这可能导致资源泄漏、初始化顺序问题。
• 从维护角度讲，如果头文件里的 static 变量本意是“跨模块共享状态”，那么它实际上无法共享，所有依赖它共享状态的代码都会在运行时各怀鬼胎。这种 bug 用肉眼几乎无法从代码层面看出来，除非打日志打印地址，否则可能排查很久。

5.3 防重复包含与 static 的边界

还有一个容易混淆的概念：头文件里的 #ifndef / #pragma once 和 static 是两回事。

#ifndef SHARED_H 防止的是“同一个 .c 文件里多次 #include 同一个头文件”导致的重复定义。它只作用于当前翻译单元。而 static 解决的是“多个翻译单元各自包含后互不冲突”。这两个机制叠加后，效果是：每个 .c 文件只展开一份头文件内容，并且这份内容中的 static 变量只属于当前 .c。

如果头文件里写的是普通全局变量定义 int counter = 0;，即使加了 #ifndef 头文件保护，多个 .c 文件包含后照样会链接冲突。原因在于，头文件保护只保证“同一个 .c 文件预处理时不会把内容贴两遍”，并不能阻止“不同的 .c 文件各自贴了一遍”。

6. 一个真实工程陷阱：配置文件里的 static 变量如何让两个模块“各自为政”

6.1 场景还原

有一回一个嵌入式项目里出现了诡异的“状态不同步”问题。代码里有一个 config.h，内容大致是：

c复制#ifndef CONFIG_H
#define CONFIG_H

static int g_ble_connected = 0;

#endif

蓝牙协议栈模块的 .c 文件包含 config.h，在连接成功回调里把 g_ble_connected = 1;；界面模块的 .c 文件也包含 config.h，在绘制界面时需要读取 g_ble_connected 来决定显示“已连接”还是“未连接”。结果界面上永远显示“未连接”。

代码 review 了好几遍，变量名一样、头文件引用路径一致，怎么看都不应该出问题。后来我在两个模块里分别打印了 &g_ble_connected，发现地址完全不同，一下子明白了：这个 static 变量在头文件里，被两个 .c 文件包含后，各有一份独立副本。蓝牙模块改的是自己那一份，界面模块读的是自己那一份，状态自然不同步。

6.2 修复方案

把 config.h 里的定义拆成声明和实现：

c复制// config.h
#ifndef CONFIG_H
#define CONFIG_H

extern int g_ble_connected;

#endif

c复制// config.c
#include "config.h"

int g_ble_connected = 0;

这样两个模块通过 extern 引用同一个全局符号，共享一份状态。标准做法是：定义只能在一个 .c 文件里出现一次，其他文件通过头文件里的 extern 声明访问。

6.3 这类问题的识别套路

遇到“两个模块都用了同一个变量名，但行为却不同步”的情况，我一般按下面的顺序排查：

1. 先打印两个模块中该变量的地址，确认它们是否指向同一块内存。
2. 如果地址不同，去头文件里找这个变量的定义，看前面有没有 static。
3. 用 nm 或 objdump -t 查看两个目标文件中该符号的类型，小写字母说明是 local 符号。
4. 全局搜一下“头文件里是否还有类似 static int g_ 的变量定义”，这种形式通常都不适合承担跨模块状态的职责。

6.4 编码规范建议

经过这些教训，我后来给团队定的几条约定：

• 头文件里通常只放：类型定义、宏、enum、extern 变量声明、函数原型、static inline 小函数。
• 头文件里尽量避免非 const 全局变量的定义，尤其是 static 变量定义，除非你有意要“每个翻译单元独立副本”这个效果。
• 需要跨文件共享的状态变量，在某个 .c 文件里定义，在头文件里用 extern 声明。
• 需要一个全局单例，但不想暴露可变全局变量时，可以用 getter/setter 函数封装。例如在 config.c 里定义 static int g_ble_connected = 0;，提供 void set_ble_connected(int) 和 int get_ble_connected(void) 两个接口。这样既能跨文件共享状态，又能把可变状态封装在实现文件里，避免全局污染。

7. 我的自查方法与最小实验技巧

7.1 一句话结论

#include 本质是文本复制，static 变量在文件作用域的关键作用是内部链接。二者叠加，结论就是：一个头文件里的 static 变量，被多少个翻译单元包含，就有多少个独立副本。

7.2 遇到这类问题，我会怎么自查

多文件 C 工程里，每次涉及“这个变量是不是共享的”这类问题，我不会凭记忆下结论，而是快速做三件事：

1. 看代码：先在符号定义位置确认前修饰符是 static、extern 还是普通全局。
2. 看目标文件：用 nm 查看符号类型，local 还是 global。
3. 看运行时地址：在多个模块里打印地址判断是不是同一份数据。

这三步基本能在五分钟内定位绝大多数 static 与 #include 相关的状态问题。

7.3 最小实验法的好处

如果只是纸上谈兵，很多人记不住也容易搞混。我建议遇到拿不准的 C 语言语义时，都建一个最小目录，里面放几个不超过二十行的源文件，把编译命令跑一遍，观察实际结果。比如本文主实验就是这样一个结构。真实项目里往往有几万行代码，变量同名的情况很常见，反而会掩盖问题的本质；最小实验可以把语义问题单独剥出来，看得一清二楚。

7.4 最后一个个人心得

我在头文件写过 static 变量，也为此调试过很久。现在写公共头文件时，我会下意识多想一句：这个变量到底是想让谁看见？如果答案是“所有包含我的模块都能看到同一份数据”，那就不能用 static。凡是犹豫不决的时候，宁可用 getter 函数，也不要让一个 static 全局变量从头文件里溜出来。这个习惯帮我在后来的项目里避开过好几类“看起来像并发问题、实际上是多副本问题”的奇怪故障。