C/C++ 多文件編程陷阱：static、extern 與 multiple definition 深度避坑指南

問題現場：經典 multiple definition 錯誤

場景：頭文件 a.h 定義全局變量 int mAge = 0;，多個 .c/.cpp 包含該頭文件，鏈接時報錯：

multiple definition of `mAge'
first defined in a.o

原因：int mAge = 0; 是定義 (分配存儲)，每個包含該頭文件的編譯單元都會產生一份副本，鏈接時發現多個同名符號衝突。

三種修正方案對比

static 陷阱實測：為什麼「編譯通過但邏輯錯」？

/* a.h */
static int mAge = 0;
void setAge(int age);
int getAge(void);

/* a.c */
#include "a.h"
void setAge(int age) { mAge = age; }
int getAge(void) { return mAge; }

/* main.c */
#include "a.h"
#include 
int main() {
    setAge(22);
    printf("direct: %d\n", mAge);   // 輸出 0 !!!
    printf("getter: %d\n", getAge()); // 輸出 22
    return 0;
}

原理：static 使變量具有內部鏈接，每個 #include "a.h" 的翻譯單元 (main.c, a.c) 都獲得一個獨立的 mAge 副本。setAge 修改的是 a.c 的副本，main.c 直接讀取的是自己的副本 (仍為 0)。這是極其隱蔽的 Bug 來源！

正確模式：聲明與定義分離 (最佳實踐)

a.h — 僅聲明接口

#ifndef A_H
#define A_H

#ifdef __cplusplus
extern "C" {
#endif

/* 變量聲明：extern 告訴編譯器「定義在別處」 */
extern int mAge;

/* 接口聲明 */
void setAge(int age);
int getAge(void);

#ifdef __cplusplus
}
#endif
#endif

a.c — 唯一定義與實現

#include "a.h"

/* 變量定義：分配存儲，初始化 */
int mAge = 0;

void setAge(int age) { mAge = age; }
int getAge(void) { return mAge; }

main.c — 使用者

#include "a.h"
#include 

int main() {
    setAge(22);
    printf("Age = %d\n", getAge()); // 正確輸出 22
    // 如需直接讀取：extern int mAge; 已在頭文件聲明
    printf("Direct = %d\n", mAge);  // 同樣正確
    return 0;
}

進階：常量、函數、C++ 類靜態成員

鏈接器視角：符號表與 ODR

• 定義：分配存儲、初始化、生成符號表條目 (強符號/弱符號)。
• 聲明：告知類型、名稱、鏈接屬性，不分配存儲。
• ODR (One Definition Rule)：整個程序中，每個非內聯實體只能有一個定義。違反導致多重定義錯誤 (強符號衝突) 或靜態局部副本 (internal linkage)。

避坑檢查清單

1. ❌ 头文件中不要定義非 static const / inline 變量。
2. ✅ 头文件用 extern 聲明全局變量/函數。
3. ✅ 仅在一個 .c/.cpp 中定義 (分配存儲)。
4. ⚠️ static 在頭文件 = 每個 .c 一份副本，極少用於數據共享，僅用於文件內部私有輔助變量/函數。
5. 🔧 C++17 專案優先用 inline 變量/函數簡化頭文件定義。
6. 🔍 編譯報錯 multiple definition → 檢查頭文件是否有定義、是否重複包含無護衛宏、是否誤將 .c 包含進 .c。

總結

「聲明在 .h，定義在 .c」 是 C/C++ 多文件編程的鐵律。理解 extern (外部鏈接)、static (內部鏈接)、inline (C++17 ODR 豁免) 的語義差異，能從根源上杜絕 multiple definition 與「邏輯正確但運行錯誤」的隱性 Bug。下次看到頭文件裡寫 int x = 0;，請果斷重構！