Apple 將 Apple silicon 架構建置錯誤整理在技術說明 TN3117;這類報錯常見根因,是依賴只有 iOS 真機 arm64 切片,沒有 iOS Simulator 對應切片。

症狀: Xcode 顯示 building for iOS Simulator but linking in object file built for iOS。
最快解法: 先核對錯誤指向的二進位檔與平台,再更新供應商提供的 XCFramework,或按目標平台重建;不要先把排除 arm64 當成通用修復。

這篇適合遷移到 Apple silicon 後遇到模擬器連結失敗的 iOS 開發者、使用預編譯庫或第三方 SDK 的工程師,以及維護 XCFramework 平台切片的建置工程師。
如果你的專案只用原始碼依賴、沒有連結任何預編譯二進位檔,這篇故障排查路徑可能不是首要方向。

Xcode building for iOS Simulator but linking in object file built for iOS,先看清報錯邊界

錯誤訊息裏的 Simulator 指向目前的建置目的地;iOS 說明二進位檔被標記的平台類型;arm64 則是處理器架構名稱。三者不能混為一談:Apple silicon Mac 的模擬器可以使用 arm64,但供 iOS 真機使用的 arm64 二進位檔,不會因此自動成為模擬器可連結的產物。Apple 對這類架構與預編譯庫錯誤的說明,亦提醒開發者先確認建置目標與相依二進位檔的支援情況:Apple silicon 建置錯誤說明。

先從完整錯誤內容找出被點名的檔案或套件,再確認失敗的是 App、測試 target,還是某個擴充功能。接着記下目前的目的地是 iOS Simulator 還是真機。若只看到 arm64 就改動整個專案的架構設定,很容易把平台切片問題誤判為 CPU 架構問題。

修復路徑 適用情況 修復評分 主要風險
更新第三方依賴 供應商已有包含模擬器平台切片的新版本 A:優先 更新可能帶入 API 或版本變更,須重新驗收
重建 XCFramework 你維護該靜態庫或框架,並能取得來源碼 A:根因可控 不同平台的產物與打包參數必須正確
設定 EXCLUDED_ARCHS 已確認特定 target 或架構暫不受支援,且有測試依據 C:僅限暫用 可能只掩蓋問題,或令其他建置目的地失敗

評分是依「是否處理平台根因」和「是否可能影響其他建置目標」作出的修復優先級判斷,不是效能測試結果。

building for iOS Simulator but linking in object file built for iOS 要怎麼處理?

先確認這不是編譯原始碼時出錯,而是連結器拿到不符合目前目的地的平台產物。錯誤中指名的 .a、.framework 或套件,通常就是排查起點。若錯誤來自第三方 SDK,不要只在 App target 裏搜尋 arm64;還要查明該依賴實際解析到哪個二進位檔,以及它由哪個版本或建置流程產生。

Apple 的 XCFramework 說明指出,這類套件可用來打包不同平台或變體的框架;因此,檢查時不能只問「有沒有 arm64」,還要核對產物的平台與是否標示為模擬器變體:建立多平台二進位框架套件。

第一步:記錄失敗的 target 與目的地

在 Xcode 的建置紀錄中複製完整錯誤,記下被點名的二進位檔名稱、失敗 target,以及當前選取的目的地。若錯誤只在測試 target 出現,應先檢查測試 target 所連結的依賴,不能直接假設主 App 的依賴設定也有問題。

第二步:檢查 XCFramework 的平台資訊

若依賴是 XCFramework,檢視其 Info.plist 中每個 library entry 的 SupportedPlatform、SupportedPlatformVariant 和 SupportedArchitectures。你要確認的不只是清單中有沒有 arm64,而是該架構是否屬於 iOS Simulator 的平台切片。Apple 的多平台框架說明以平台與變體區分套件內容,應以這些資訊判斷產物適用範圍,而非只看檔名或架構標記。

若手上是單一 .a 或舊式 .framework,lipo -archs 可以協助查看架構,但它不能單獨證明該二進位檔是為模擬器而建。當平台資訊無法從包裝內容確認,向供應商索取產物清單,或用實際建置結果驗證,會比猜測更可靠。

為何 iOS 真機 arm64 庫不能直接連結到模擬器?

arm64 描述的是 CPU 架構,不是完整的平台身分。相同架構名稱可能出現在不同平台的二進位檔中;連結時,Xcode 還要判斷產物是否符合目前的建置目的地。Apple 在 TN3117 對預編譯庫與 Apple silicon 建置錯誤的說明,將問題指向依賴是否提供適用的架構產物,而不是一概把模擬器視為不支援 arm64。

這也解釋了為什麼「真機能編、模擬器不能編」很有診斷價值:真機建置成功,只能證明目前選用的真機產物可用,不能證明同一套依賴也包含模擬器所需的平台變體。Apple 關於在模擬裝置或實體裝置上執行 App 的文件,亦將兩種目的地分開說明:在模擬裝置或實體裝置上建置與執行。

判斷時可採用以下順序:先確認目的地,再看依賴的平台變體,最後才看架構。若順序倒過來,一看到 arm64 就排除它,可能只是讓錯誤暫時消失,沒有補上缺少的模擬器產物。

第三方 SDK 缺少 Simulator arm64 slice 時怎麼辦?

先確認供應商是否已發布含模擬器切片的版本。對第三方二進位 SDK 而言,這通常比在消費端專案自行拼接架構設定更穩妥。更新前記下現行 SDK 版本與來源,更新後重新解析套件,再確認實際被拉取的產物確實包含模擬器變體。若 SDK 以 Swift Package 發佈,Apple 對二進位 Swift 套件的文件可作為核對套件與二進位依賴關係的參考:以 Swift Package 發佈二進位框架。

如果供應商尚未提供合適產物,先詢問預計支援版本與替代方案;不要把來源不明的二進位檔複製進 XCFramework,或僅靠改名假裝它適用於模擬器。若供應商沒有可用版本,而你又無法取得原始碼,通常只能暫時改用其他可支援的依賴版本、避免在該目的地執行相關測試,或等待供應商補齊產物。這些都是有代價的暫行處理,不等同於修復 SDK。

第三步:按依賴來源選擇更新或重建

  • 第三方預編譯庫: 優先升級到供應商明確支援 iOS Simulator 的版本,並核對變更紀錄與套件來源。
  • 專案自建靜態庫: 以對應平台重新建置,分別產生真機與模擬器所需產物,再依 Apple 的方式打包成 XCFramework。Apple 的多平台二進位框架建立說明提供了按平台組合框架的依據。
  • 原始碼依賴: 優先讓依賴隨目前建置目的地編譯;若套件設定仍引用預編譯檔,則回到實際解析到的二進位產物檢查。

自建產物時,將各平台的建置與打包步驟記錄在版本控制中。只保存最後的 XCFramework、卻不記錄來源提交與建置參數,會讓下一次更新難以確認哪個切片被替換。

EXCLUDED_ARCHS 能解決 Xcode 模擬器架構錯誤嗎?

它可以在經過驗證的特定情境下作為暫時繞行方式,但不是補齊缺失平台切片的方法。若把 EXCLUDED_ARCHS 設成全專案預設值,可能令其他 target、其他目的地或套件建置無法使用原本需要的架構。Apple 的 Xcode 建置設定參考將 EXCLUDED_ARCHS 列為建置設定;實際效果須看設定套用到哪個組態、SDK 與 target,不能只憑一行設定推論全專案結果。

只有在你已明確確認是哪個依賴或 target 不支援某架構,而且能驗收相關建置目的地時,才考慮狹義設定。改動後要檢查設定究竟套用於 Debug、Release,還是特定 SDK;並在專案分支或變更紀錄中註明移除條件。若目標是讓 Apple silicon 模擬器正常連結,優先更新依賴或重建 XCFramework,通常更直接地處理根因。

第四步:用可勾選清單完成雙目標驗收

先在預期使用的 iOS Simulator 目的地建置,再切換到實體 iOS 裝置目的地建置。兩種目的地都成功,才表示目前依賴產物能滿足這兩條建置路徑;單獨通過其中一種,不能代替另一種驗收。

  • [ ] 記錄失敗時的完整錯誤、target、目的地與被點名的依賴檔案。
  • [ ] 確認依賴是第三方二進位 SDK、自建靜態庫,還是原始碼套件。
  • [ ] 檢查 XCFramework 的平台、變體與架構資訊,不以 arm64 字樣單獨判斷相容性。
  • [ ] 更新供應商產物,或按目標平台重新建置並打包 XCFramework。
  • [ ] 若曾調整 EXCLUDED_ARCHS,確認變更只作用於必要的 target 與組態,並記下回退方式。
  • [ ] 分別在模擬器與真機目的地建置,確認錯誤沒有轉移到其他 target。
  • [ ] 記錄依賴版本、產物來源與驗收結果,供工具鏈或依賴升級後比對。

如果清單中任何一項無法確認,先不要把架構排除設定併入共用分支;保留錯誤紀錄並回到依賴產物查證,能避免把本機暫時可用誤當成團隊層級的修復。

何時需要另一個隔離環境重現

若更新依賴後,本機仍出現不同結果,可能需要排除本機快取、既有建置資料或未同步的設定差異。這時可在另一台 Mac 或隔離環境,以相同提交、依賴版本和建置目的地重跑模擬器與真機驗收。這不是替代根因分析,而是用來確認問題是否隨專案產物重現。

如果你已有穩定且可控的本機 Mac,並需要長期建置、連接實體周邊或直接操作測試裝置,維持本機環境通常更合適。相反地,當你暫時沒有第二台 Mac 可交叉驗證,本機又可能受快取或工具鏈狀態影響時,租用 Mac 作短期隔離測試能提供另一個建置環境;你可先了解 SSHMac 的環境使用與連線說明,再按實際需要透過 SSHMac 開啟環境。此類測試應沿用同一份專案與依賴鎖定資料,並明確記錄模擬器和真機兩邊的結果。