Xcode 鏈接錯誤 `ld: Assertion failed: (memberIndex != 0)`：靜態庫損壞/架構不匹配，清理重建解決

錯誤堆棧

ld: Assertion failed: (memberIndex != 0), function makeObjectFileForMember,
file .../archive_file.cpp, line 355.
clang: error: linker command failed with exit code 1

核心原因

鏈接器 (`ld`) 讀取 **靜態庫 (.a)** 時，解析成員索引失敗。常見誘因：

1. 靜態庫文件損壞/不完整：下載中斷、磁盤錯誤、Git LFS 未拉取實際內容。
2. 架構切片缺失：庫僅包含 `arm64`，但構建目標含 `armv7`/`x86_64` (模擬器)；或反之。
3. 庫文件格式不正：非標準 `ar` 打包、被錯誤壓縮/加密。
4. Xcode/Command Line Tools 版本不匹配：舊版 `ld` 無法解析新版 `ar` 生成的索引格式。

排查與修復步驟

1. 清理構建產物：
   Xcode → Product → Clean Build Folder (Shift+Cmd+K)。
   刪除 `~/Library/Developer/Xcode/DerivedData/` 對應項目目錄。
2. 驗證靜態庫架構：
   終端執行：lipo -info /path/to/libxxx.a
   輸出應包含目標架構，如：`Architectures in the fat file: libxxx.a are: armv7 arm64 x86_64`。
   若缺失，需重新編譯或下載完整 Fat 二進制庫。
3. 重新生成庫索引：
   ranlib /path/to/libxxx.a (修復 `.a` 符號表索引)。
4. 檢查 Build Settings：
   - Valid Architectures (舊版) / Architectures (新版) 包含 `arm64` (真機) + `x86_64` (模擬器)。
   - Build Active Architecture Only = No (Debug 也建議 No，確保模擬器可用)。
   - Other Linker Flags 無殘留錯誤路徑。
5. CocoaPods / Carthage / SPM 依賴：
   - `pod deintegrate && pod install` (清理重裝)。
   - `carthage update --use-xcframeworks --platform iOS` (強制重建)。
   - SPM: File → Packages → Reset Package Caches → Resolve Package Versions。
6. 升級 Xcode / Command Line Tools：
   Mac App Store 更新 Xcode，或 `xcode-select --install` 更新 CLI 工具。

終極排查：最小復現項目

1. 新建空的 iOS Single View App。
2. 僅添加該靜態庫到 Frameworks, Libraries, and Embedded Content。
3. 構建 → 若報同樣錯誤，確認庫本身有問題，聯繫庫提供方或換源。
   若正常，說明主項目配置污染，對比 Build Settings 差異。

避坑口訣

• 靜態庫必須是 Fat Binary (多架構合一)，單切片庫在模擬器/真機切換時必崩。
• 版本控制不要提交 .a 文件（二進制難 diff、易損壞），用包管理器鎖定版本。
• DerivedData 定期清理，避免舊索引干擾新構建。

「Clean → lipo 驗證 → ranlib 修復 → 依賴管理器重裝」四步走，解決 99% `memberIndex != 0` 鏈接斷言失敗。