AI Skills
spm-build-analysis

spm-build-analysis

熱門

分析 Swift Package Manager 的相依性、套件插件、模組變體以及 CI 導向的建置開銷，這些因素會拖慢 Xcode 建置速度。當開發者懷疑套件、插件或相依圖形狀影響乾淨或增量建置效能、提及 SPM 緩慢、套件解析時間、建置插件開銷、因配置差異導致重複模組建置、模組間的循環相依、過大模組需要拆分或模組化最佳實務時使用。

1185星標
45分支
更新於 2026/4/15
獲取技能源代碼

相關技能

recipe-create-expense-tracker2.9萬openhue39萬eightctl38萬
SKILL.md
唯讀
名稱
spm-build-analysis
描述

分析 Swift Package Manager 的相依性、套件插件、模組變體以及 CI 導向的建置開銷，這些因素會拖慢 Xcode 建置速度。當開發者懷疑套件、插件或相依圖形狀影響乾淨或增量建置效能、提及 SPM 緩慢、套件解析時間、建置插件開銷、因配置差異導致重複模組建置、模組間的循環相依、過大模組需要拆分或模組化最佳實務時使用。

SPM 建置分析

當套件結構、插件或相依配置可能導致 Xcode 建置緩慢時，使用此技能。

核心規則

  • 將套件分析視為蒐集證據，而非強制取代相依套件。
  • 區分套件圖形問題與專案設定問題。
  • 未經明確許可，不得改寫套件清單或相依來源。

檢查項目

  • Package.swift 與 Package.resolved
  • 本地套件 vs 遠端套件
  • 套件插件與建置工具的使用
  • 二進位目標的佔用空間
  • 相依層級、重複匯入與潛在循環
  • 顯示套件相關工作的建置記錄或時間摘要

推薦前的驗證

在推薦中包含任何本地套件之前，請確認它確實是專案相依圖的一部分。Vendor/ 目錄可能包含未連結到任何目標的套件。

  • 檢查 project.pbxproj 中是否有 XCLocalSwiftPackageReference 項目參照該套件路徑。
  • 檢查 XCSwiftPackageProductDependency 項目，確認套件的產品已連結到至少一個目標。
  • 如果本地套件存在於磁碟但未在專案中被參照，請勿將其納入建置時間的建議中。

當建議為分支追蹤的相依套件鎖定版本時：

  • 使用輔助腳本一次掃描所有分支鎖定的相依套件：
    python3 scripts/check_spm_pins.py --project App.xcodeproj
    此腳本會對每個分支鎖定的套件檢查 git ls-remote --tags，並回報哪些套件有可用的標籤可供鎖定。
  • 如果沒有標籤，建議鎖定到特定的提交修訂哈希以確保確定性。
  • 註明哪些套件因上游沒有標籤而使用分支鎖定，以及哪些套件雖有標籤但故意追蹤分支。

重點關注領域

  • 套件圖形形狀以及變更觸發的下游工作量
  • 本地開發與 CI 期間的插件開銷
  • 在乾淨環境中出現的檢出或擷取成本信號
  • 導致重複模組建置的配置差異
  • 使用不同巨集或選項但共享相依套件的套件目標所帶來的風險
  • 相依方向違規（功能互相依賴而非共享較低層）
  • 模組間的循環相依（將共享合約提取到協定模組）
  • 過大模組（200+ 檔案）會擴大增量重建範圍
  • 使用 @_exported import 的傘狀模組會建立隱藏的相依鏈
  • 缺少介面/實作分離會阻礙建置平行化
  • 測試目標依賴應用目標而非被測模組
  • Swift 巨集重建串聯：大量使用 Swift 巨集（例如 TCA、基於 swift-syntax 的函式庫）可能導致微小的原始碼變更串聯成近乎完整的重建，因為巨集展開會使下游模組失效
  • swift-syntax 在沒有預先建置的二進位檔時會通用建置（所有架構），增加顯著的乾淨建置開銷
  • 多平台建置倍增：加入次要平台目標（例如 watchOS）可能導致共享的 SPM 套件建置多次（例如 iOS arm64、iOS x86_64、watchOS arm64），使 SwiftCompile、SwiftEmitModule 和 ScanDependencies 任務倍增

模組化 SDK 遷移注意事項

將相依套件從單體目標遷移到模組化多目標 SDK（例如將一個傘狀函式庫替換為獨立的 Core、RUM、Logs、Trace 模組）並不會自動減少建置時間。模組化目標會增加 SwiftCompile、SwiftEmitModule 和 ScanDependencies 任務的數量，因為每個目標都必須獨立編譯、掃描並發出模組。建置時間的取捨取決於專案的平行化空間以及實際需要多少個模組化目標。

在考慮模組化 SDK 遷移時：

  • 比較遷移前後的 SwiftCompile 任務總數。
  • 在推薦遷移以提升建置速度之前，先對兩種配置進行基準測試。
  • 如果動機是減少 API 表面（只匯入你使用的部分），請注意建置時間可能持平或增加，但匯入整潔度會提升。
  • 僅在專案目前編譯了單體 SDK 中大量未使用的部分，且模組化替代方案能完全跳過這些未使用部分時，才推薦為建置速度進行模組化 SDK 遷移。

明確模組相依角度

當同一個模組在時間輸出中多次出現時，調查是否不同的套件或目標選項強制產生了額外的模組變體。統一的選項通常比削減少量原始碼更重要。

報告格式

對於每個發現，請包含：

  • 證據
  • 受影響的套件或插件
  • 對乾淨建置與增量建置的影響
  • CI 影響（如果相關）
  • 估計影響
  • 核准要求

如果主要問題與套件無關，請透過讀取目標技能的 SKILL.md 並將其工作流程應用於相同專案上下文，轉交給 xcode-project-analyzer 或 xcode-compilation-analyzer。

其他資源