症狀：課程程式碼可以開啟，卻一直停在 Resolving Package Graph，或出現 Swift Package Manager 下載失敗。
最快解法：先用瀏覽器或 Git 驗證倉庫能否存取，再看 Xcode 的套件解析資訊，最後核對版本規則與 Package.resolved；不要一開始就刪除所有快取。
這篇文章適合第一次替 SwiftUI 課程專案加入第三方套件、看不懂版本解析錯誤的零基礎學生。 如果你打開老師或 GitHub 範例專案後卡在依賴下載，或使用學校電腦、受限網路、私有倉庫，也可以按下面流程逐項判斷。
最後更新於 2026 年 8 月 30 日；Xcode 版本與套件管理流程核實自 Apple 的 Xcode 26.6 發布說明及 Apple、Swift 官方文件。
先把錯誤分成四類，再決定修法
課程專案能打開，不代表套件已經成功取得。Swift Package Manager 可以想成替專案借教材：倉庫網址是圖書館地址，版本規則是你允許借的版本範圍，而 Package.resolved 則像借書紀錄，記下這次實際拿到哪個版本。
你先保存完整錯誤文字、套件倉庫網址、操作步驟與發生時間，再觀察錯誤停在哪裡：
- 倉庫頁面完全打不開：優先查網址、DNS、代理或網路限制。
- 下載過程中斷：查連線、憑證檢查、網域限制與 Xcode 記錄。
- 版本無法解析：查
Package.swift的相依性宣告、工具版本與可用版本。 - 套件已取得但編譯失敗：這通常已不是單純下載問題，應看產品選擇、平台條件與原始碼相容性。
第一次加入公開套件：先驗證網址，再用空白專案縮小範圍
如果你是第一次在 Xcode 26.6 加入公開套件，先不要複製同學的整個專案設定。按照以下順序操作：
- 從課程提供的套件網址開啟倉庫首頁，確認不是文件頁、下載頁或多了一段標點符號的錯誤網址。
- 在終端機以 Git 讀取遠端倉庫，例如使用唯讀的
git ls-remote驗證遠端是否回應。這一步只讀取資訊，不會修改課程專案。 - 在 Xcode 的套件相依性設定中重新確認倉庫 URL、版本規則與要加入的產品。介面名稱若因版本或專案類型略有差異，應以 Apple 的套件文件為準。
- 建立一個空白測試專案，只加入同一個公開套件，觀察能否完成解析。
- 將空白專案的結果與原課程專案比較：若空白專案成功，問題多半在原專案的宣告、平台條件或既有鎖定版本；若兩者都失敗，才回頭查 Mac 的網路或權限環境。
範例專案卡住：保留 Package.resolved，不把刪除檔案當萬用解
打開老師的 GitHub 範例專案後，Package.resolved 可能已經記錄課程作者選定的精確版本。它不是套件本體，也不是單純的暫存檔；刪除後重新解析，可能取得另一組符合範圍的版本，結果是下載成功了，課程程式碼卻出現新的 API 或編譯錯誤。
請先做一份副本，再比較三項內容：
Package.resolved目前鎖定的套件版本與提交識別。- 專案或
Package.swift宣告的最低版本、版本範圍與相依套件。 - 套件倉庫目前仍然存在的標籤、分支或提交。
Xcode 一直顯示 resolving package graph 時，先看解析資訊和錯誤日誌，不要立刻刪除 Package.resolved。只有在你確認課程方要求更新鎖定版本、或已經備份並知道要接受版本變更時，才進行重新解析。若版本無解仍然存在，停止重試，向課程提供者確認應使用的提交或版本範圍。
受限學校電腦：用三個讀取測試確認問題邊界
學校網路無法添加 Swift 軟體包時，問題可能不是你的程式碼，而是代理伺服器、憑證檢查、網域封鎖，或你沒有安裝與修改開發工具的權限。你可以用三個不涉及繞過管理措施的測試判斷：
- 瀏覽器測試：開啟倉庫首頁與套件作者提供的相關頁面，記下是否逾時、重新導向或顯示憑證警告。
- Git 讀取測試：使用唯讀方式取得遠端參考資料；若瀏覽器可開啟但 Git 失敗，可能是 Git 連線被代理或憑證政策攔截。
- Xcode 記錄測試：保存套件解析時顯示的錯誤，不要只截取最後一行。Apple 的 Xcode 常見設定與建置問題說明可協助你確認應從設定、套件或建置階段查起。
若倉庫本身正常，但學校電腦的網路與安裝權限始終不允許解析，可以參考 MACGPU 的遠端 Mac 學習環境，在合規條件明確的環境以同一份專案繼續驗證，而不是自行修改受管理的電腦。
私有小組倉庫：把帳號權限、連線方式與鎖定版本分開查
私有套件需要身份驗證，和公開套件的下載失敗不是同一件事。先確認你的帳號確實有倉庫讀取權限；只有能登入程式碼平台，不代表一定能讀取小組的私有相依性。
接著分開檢查：
- HTTPS 憑證處理的是以 HTTPS 讀取遠端倉庫時的身份驗證。
- SSH 金鑰處理的是 SSH 連線身份，不會自動修正錯誤的套件版本規則。
Package.resolved處理的是專案要使用哪個已解析版本，不會替你授予私有倉庫權限。
如果你能讀取測試倉庫，卻無法讀取課程私有套件，停止修改本機設定，請小組管理員確認倉庫權限與正確提交；如果公開套件也無法讀取，則回到網路或學校裝置限制排查。
本機、學校電腦與遠端 Mac 的驗收路線
你需要比較的是「同一專案、同一提交、同一套件版本」，而不是只看某台電腦能否打開 Xcode。Apple 也提供在持續整合流程中建置使用 Swift 套件之專案的說明，可參考 Apple 的 Swift 套件建置流程理解為何要固定輸入條件。
先完成下面清單：
- [ ] 保存原專案副本、目前 Git 提交、倉庫 URL 與完整錯誤文字。
- [ ] 用瀏覽器確認公開倉庫能開啟，並用 Git 做一次唯讀存取測試。
- [ ] 在 Xcode 中確認套件產品、版本規則與平台條件。
- [ ] 備份並檢查
Package.resolved，記錄重新解析前後差異。 - [ ] 用同一專案在另一個合規 Mac 環境進行首次解析。
- [ ] 關閉並重新開啟專案，再確認套件是否能再次解析。
- [ ] 實際建置 SwiftUI 專案，確認不是「套件下載成功但程式碼不相容」。
- [ ] 若只有原設備失敗，將問題歸入網路、快取或權限環境；若乾淨環境也失敗，回到倉庫權限或版本宣告。
排錯對照表：先看哪一層
| 觀察到的現象 | 優先驗證 | 不應先做的事 | 停止條件 |
|---|---|---|---|
| 倉庫首頁無法開啟 | URL、網路、代理與憑證 | 反覆改版本 | 瀏覽器與 Git 都無法讀取 |
| 只停在解析圖形 | Package.resolved、版本規則與 Xcode 記錄 | 直接刪鎖定檔 | 版本條件仍然無解 |
| 公開套件可讀，私有套件失敗 | 帳號與倉庫讀取權限 | 借用同學憑證 | 管理員未確認權限 |
| 套件已下載但建置失敗 | 產品選擇、平台條件與原始碼 | 再次下載同一套件 | 下載階段已經成功 |
| 乾淨 Mac 仍然失敗 | 倉庫提交與版本宣告 | 繼續清除本機資料 | 課程方需更新依賴設定 |
不同學習環境的方案比較
| 環境 | 優點 | 主要限制 | 適合度 |
|---|---|---|---|
| 學校電腦 | 不必另外準備設備 | 網路代理、安裝權限與安全政策可能不可改 | ★★☆☆☆ |
| 個人本機 Mac | 連線與權限較容易控制 | 需要自行維護系統、工具與儲存空間 | ★★★★☆ |
| 合規遠端 Mac | 可在明確的 macOS 環境測試 Xcode 專案 | 受連線品質與遠端操作方式影響 | ★★★★☆ |
| 只有 Windows 電腦 | 適合編寫部分跨平台程式碼 | 無法直接取代 Xcode 的 macOS 建置與測試環境 | ★★☆☆☆ |
修復方式的成本與風險評分
| 方法 | 能處理的問題 | 風險 | 建議評分 |
|---|---|---|---|
| 重新確認倉庫 URL | 網址錯誤、複製多餘字元 | 低 | ★★★★★ |
| 瀏覽器與 Git 讀取測試 | 網路、代理、倉庫可用性 | 低 | ★★★★★ |
| 備份後重新解析 | 鎖定版本過舊或需要更新 | 中 | ★★★☆☆ |
刪除 Package.resolved | 只適用於已知要重建依賴的情況 | 中至高 | ★★☆☆☆ |
| 重裝 Xcode | 少數本機安裝損壞情況 | 高，且不解決權限問題 | ★☆☆☆☆ |
| 更換合規 Mac 環境 | 原設備受網路或權限限制 | 需重新準備連線與檔案 | ★★★★☆ |
真正值得避免的是把「可以連線」誤認為「依賴一定能解析」。學校方案常見的限制是代理不可改、安裝權限不足，以及同一專案在不同設備留下不一致的鎖定版本；相較之下，租用 MACGPU 能讓你在較明確的 Mac 環境中重現同一專案，但遠端連線本身仍需保持穩定。先用清單完成一次可重現驗收，再決定修復原設備或更換學習環境，通常比盲目清快取更安全。