徹底解決 VC++ LNK2005「符號已定義」鏈接錯誤：從原理到實戰

前言

許多 VC++ 使用者遇過 LNK2005: symbol already defined 和 LNK1169: one or more multiply defined symbols found 鏈接錯誤，常發生於使用第三方庫時。本文從編譯鏈接原理出發，徹底解析成因與解決之道。

編譯鏈接兩階段

1. 編譯：源文件 → 組合語言 → 機器指令 + 相關資訊 → 目標文件 (.obj)。
2. 鏈接：多個目標文件/程式庫 → 完整可執行文件。

強/弱符號與鏈接器決策規則

編譯器將全域符號分為強/弱：

• 強符號：函數、已初始化的全域變數。
• 弱符號：未初始化的全域變數。
• 外部聲明 (extern) 非強非弱。

鏈接器處理多重定義規則：

1. 不允許強符號多重定義 (不同目標文件同名強符號)。
2. 符號在某目標文件為強、其他為弱 → 選強符號。
3. 所有目標文件均為弱符號 → 任選一個。

故多目標文件不可重複定義同名函數/已初始化全域變數，否則必現 LNK2005/1169。但有時自查無重定義卻報錯，何解？

靜態庫與鏈接器掃描機制

ANSI C 標準函數分散於多目標文件，直接提供極不便。C 提供靜態庫 (.lib) 打包機制：鏈接時指定庫文件，鏈接器自動尋找應用程式真正用到的目標模組並拷貝參與建構。

鏈接器解析庫引用流程 (符號解析階段)

鏈接器按命令列順序左至右掃描，維護三集合：

• E：將合併成可執行文件的目標文件集合。
• U：未解析符號集合 (已引用未定義)。
• D：已加入 E 的目標文件定義的符號集合。

初始 E、U、D 均空。處理每個輸入文件 f：

1. f 為目標文件 → 加入 E，其未解析符號入 U，已定義符號入 D，處理下一個。
2. f 為庫文件 → 嘗試用 U 中符號匹配 f 內各目標模組。若模組 m 定義了 U 中符號 → m 加入 E，其未解析符號入 U，已定義符號入 D。重複至達不動點 (U、D 不再變化)。未加入 E 的模組丟棄，處理下一輸入文件。
3. 若處理中向 D 加入已存在符號，或掃描完 U 非空 → 報錯停止。否則合併 E 輸出可執行文件。

VC 編譯器運行時庫選項與預設庫機制

VC 編譯器 cl.exe 相關選項：

編譯器在目標文件專門區域存放「預設庫」資訊，指導鏈接器掃描時加入該庫。實驗驗證：

/* main.c */ int main() { return 0; }
cl /c main.c  # 相當於 cl /c /ML main.c
// 用文本編輯器開 main.obj 搜尋 "defaultlib"
# 看到："-defaultlib:LIBC -defaultlib:OLDNAMES"

目標文件指定單執行緒靜態庫 libc.lib 與相容庫 oldnames.lib。

預設庫不一致的後果：從警告到致命錯誤

案例一：僅警告，鏈接成功

/* mylib.c */
#include <stdio.h>
void foo() { printf("%s", "I am from mylib!\n"); }
cl /c /MLd mylib.c  # 指定 libcd.lib
lib /OUT:my.lib mylib.obj  # 打包庫

/* main.c */
void foo();
int main() { foo(); return 0; }
cl /c main.c  # 預設 libc.lib
link main.obj my.lib  # 成功，僅警告 LNK4098

分析：掃描 main.obj → E={main.obj}, U={foo}, D={main}, 輸入列表加 libc.lib。掃描 my.lib → foo 解析，printf 入 U，輸入列表加 libcd.lib。掃描 libc.lib → printf 解析，U 空。掃描 libcd.lib → U 空，丟棄所有模組。成功。

案例二：致命錯誤 LNK2005/1169

/* mylib.c 修改版 */
#include <stdlib.h>
void foo() { _malloc_dbg(1, _NORMAL_BLOCK, __FILE__, __LINE__); } // 非 ANSI，需 _DEBUG
cl /c /MLd mylib.c
lib /OUT:my.lib mylib.obj
link main.obj my.lib  # 大量 LNK2005 + LNK1169

分析：_malloc_dbg 僅存在調試版庫。掃描 libc.lib 時無模組定義它，但 crt0.obj 等初始化模組仍加入 E，帶入 malloc 等符號入 D。最後掃描 libcd.lib → dbgheap.obj 定義 _malloc_dbg 加入 E，同時定義 malloc 等同名符號 → 與 D 中符號衝突 → 鏈接器中斷報錯。

解決方案

1. 擁有庫源碼：統一編譯選項 (如全用 /MLd 或全用 /ML) 重編打包。
2. 第三方庫無源碼：用 dumpbin /DIRECTIVES my.lib 查看庫模組指定的預設庫 (輸出中 -defaultlib:XXXX)，再用匹配選項編譯自有程式。
3. IDE 用戶：專案屬性 → C/C++ → 代碼生成 → 運行時庫 設定，效果等同命令列選項。

核心原則：確保所有參與鏈接的目標文件/庫指定一致的預設運行時庫版本。