近來接手了同事負責的靜態庫工作,難免要做整合與除錯。結果整合之後,一直出現 linker command failed with exit code 1 這個錯誤。查了不少資料才解決,今天把這個問題系統性地整理一遍,一方面記錄自己這次的解法,一方面把其他常見成因歸納列出,免得以後再摔同樣的跤。
先說我遇到的這個:靜態庫的對應路徑設定不正確,導致 linker 找不到庫。把 Library Search Paths 修好即可解決。這也是這個錯誤最常見的原因之一。
症狀是錯誤訊息中出現某個類別的名稱,提示找不到對應的符號。

解法:依錯誤訊息中的類別名找到對應的 .m 檔,確認它在專案的 Compile Sources 列表中被打勾。

這個問題在多人協作時特別容易發生:衝突解決後檔案被重新加入,勾選狀態可能因此改變;或者新同事拉下來的分支裡,某些檔案根本沒被加進 target。
先做完上面第一步的檢查,然後找到 Build Settings → Linking → Other Linker Flags:

把這個屬性設為 -all_load 或 -ObjC,視情況而定,可以多試幾次。
為什麼需要 -ObjC?因為 Objective-C 的類別與分類(category)資訊不會被預設的連結流程完整帶入,靜態庫裡以 category 形式實作的功能會在執行期找不到方法而崩潰,或在連結期就報錯。加上這個旗標可以強制載入所有 Objective-C 符號。
症狀是所有用到這個庫的檔案都報錯,例如 HomeViewController.o 與 AnalysisViewController.o 同時出現問題。
這種「全面性失敗」通常指向路徑問題而非程式碼問題。解法:Build Settings → Search Paths → Library Search Paths,把靜態庫所在的目錄加進去。

順便也檢查 Header Search Paths。編譯期找不到標頭檔、連結期找不到符號,兩者症狀相似但成因不同,容易混淆。
這個情況相當普遍。兩個同名檔案(例如不同資料夾下都有 Utils.m)會造成符號重複定義,錯誤訊息中會出現 duplicate symbol。解法是重新命名其中一個,或透過 target membership 確保只有一份被編譯。
若錯誤訊息中出現某個類別名,去原始檔案看看它 import 了哪些第三方庫,把这些庫逐一註解排除,找出出錯的那一個,然後依照官方文件的步驟重新加入一遍。有時候庫檔案本身損毀,或版本與專案的其他相依性衝突,都會表現成類似的症狀。
遇到這個錯誤時,我建議按下面的順序處理,可以少走很多冤枉路:
linker command failed,它上面通常還列著真正的原因——是 undefined symbols、duplicate symbols,還是 library not found。這三者的解法完全不同。以上就是這個錯誤的一般解法。實務上它幾乎總是「專案設定」而非「程式碼邏輯」的問題,所以先別急著改程式碼,把錯誤訊息讀懂才是最快的路。
既然提到第三方靜態庫路徑的問題,下一講就來好好談談 Library Search Paths 與 Header Search Paths 的設定邏輯,那也是常見錯誤的來源之一。