xcode-project-setup

Xcode 專案設定

⛔️ 重要規則與環境檢查

在執行任何 Xcode 設定或檔案操作之前，你必須遵守以下規則。違反規則將會產生高額費用。

1. 禁止使用 Ruby

你嚴格禁止使用 Ruby、Rails 或任何 Ruby gem（包括 xcodeproj gem）。無論如何都不得撰寫或執行 Ruby 腳本。

2. 現代 Xcode 資料夾同步

現代 Xcode 專案支援資料夾同步。當新增原始碼（.swift）或資源檔案時，只需將它們寫入磁碟上的正確目錄，它們就會自動被包含在 Xcode 專案中。切勿手動修改 .pbxproj 檔案來新增檔案。

3. 允許的腳本語言

如果你必須撰寫腳本來操作專案環境（例如，設定超出 xcode_spm_setup 腳本範圍的 SPM 套件），你必須使用 Swift。只有在 Swift 完全不可行的最後手段下，才能使用 Node.js 或 TypeScript。

4. 工具鏈驗證

由於此技能完全依賴原生 Swift 腳本，你必須驗證環境：

• 在繼續之前執行 swift --version。
• 如果找不到 Swift 指令，你必須停止並建議使用者安裝 Swift 工具鏈（例如透過 macOS 的 xcode-select --install），或詢問是否可以嘗試為他們安裝。在沒有 Swift 的情況下不要嘗試繼續。

5. 靜態框架（Firebase）的必要連結旗標

當設定重度依賴內部 Objective-C 類別和 +load 方法的 SPM 相依套件（例如 Firebase iOS SDK 套件）時，Apple 連結器會在靜態連結時積極地剝離這些方法。

這會導致執行時期嚴重崩潰（例如 FirebaseAuth/Auth.swift:167: Fatal error: Unexpectedly found nil）。

提供的 xcode_spm_setup Swift 腳本在新增 Firebase 產品時會自動將 -ObjC 旗標注入到 OTHER_LDFLAGS。 然而，如果你遇到問題，仍應檢查建置設定中是否存在此旗標。

• 在新增 Firebase 相依套件時未包含此旗標是一個嚴重錯誤。

---

空目錄工作流程

如果要求你建置 iOS 應用程式或設定 Xcode 相依套件，但不存在 .xcodeproj 或 .xcworkspace，你必須要求使用者先建立專案：

「在此目錄中找不到 Xcode 專案。請手動建立一個空的 Xcode 專案，並在準備好繼續時通知我。」

等待使用者確認已透過 Xcode 建立 .xcodeproj，然後繼續執行下方的標準 Xcode 工作流程。

---

標準 Xcode 工作流程

不要使用原始文字解析、sed 或 Ruby 腳本直接修改 .pbxproj 檔案。

相反地，執行此技能附帶的 Swift 設定套件（scripts/xcode_spm_setup）來安全地安裝 SPM 套件並連結選用的設定檔案（例如 GoogleService-Info.plist）。

重要：始終使用最新 SDK 版本

為確保取得最新功能與安全性修正，請始終使用最新版本的 Firebase iOS SDK。請在 https://github.com/firebase/firebase-ios-sdk/releases 查看最新發行版本。

• 在指令中使用最新的版本號碼（例如 11.x.y），而不是硬編碼的佔位符。

了解腳本的動作

當將 Swift Package 新增到 Xcode 專案時，必須執行兩個不同的步驟：

1. 新增套件儲存庫相依性（例如 https://github.com/Alamofire/Alamofire）。
2. 選取目標（例如 MyApp），導覽至 General > Frameworks, Libraries, and Embedded Content，然後按下 + 按鈕以明確連結特定的產品模組（例如 Alamofire）。

提供的 xcode_spm_setup Swift 腳本會自動為你處理這兩個步驟。 透過將模組清單作為引數傳遞，它會安全地注入套件相依性，並自動將這些模組連接到主要目標的 Frameworks 建置階段。你不需要進行任何手動連結。

使用方式

1. 找到套件路徑： 在磁碟上找到此技能的 scripts/xcode_spm_setup 目錄的絕對路徑。
2. 執行： 使用以下簽章執行原生的 swift run 指令：

swift run --package-path <技能路徑>/scripts/xcode_spm_setup xcode_spm_setup <專案路徑.xcodeproj> <儲存庫URL> <版本需求> [--plist <選用/路徑/設定檔.plist>] <產品1> [產品2 ...]

範例 1：一般套件（例如 Alamofire）

將 Alamofire 新增到標準 Xcode 專案。請注意沒有 --plist 旗標。

swift run --package-path /Users/foo/.agents/skills/xcode-project-setup/scripts/xcode_spm_setup xcode_spm_setup MyApp.xcodeproj https://github.com/Alamofire/Alamofire 5.8.1 Alamofire

範例 2：Firebase（需要 Plist）

新增 Firebase 並自動將 GoogleService-Info.plist 連結到資源建置階段。
注意：將 11.0.0 替換為發行頁面上的實際最新版本。

swift run --package-path /Users/foo/.agents/skills/xcode-project-setup/scripts/xcode_spm_setup xcode_spm_setup MyApp.xcodeproj https://github.com/firebase/firebase-ios-sdk 11.0.0 --plist MyApp/GoogleService-Info.plist FirebaseCore FirebaseAuth FirebaseFirestore

注意：此腳本具有冪等性。它會自動跳過已存在於專案中的檔案或套件連結。