資料點:Xcode 的套件相依設定可指定版本、分支或提交修訂;Apple 的 Xcode 說明列出這些版本要求。 症狀 → 最快解法:SwiftUI 作業要加程式套件時,優先從 Xcode 的套件相依入口操作,依課程要求選版本,再確認產品已加入 App 目標並建置驗收。若作業要求在 Xcode 中完成,而你沒有可用 Mac,先確認課程規則,再安排合規的 macOS 環境。
第一次替 SwiftUI 專案加套件的學生:本文帶你找 Xcode 的操作入口,並確認套件是否真的能在 App 中使用。 課程範本已指定版本的學生:本文協助你避免擅自更新依賴,影響作業環境或組員協作。 主要使用 Windows 或學校電腦的學生:本文會幫你判斷完成作業是否需要可用的 Mac 與 Xcode。
先確認你要加的是課程依賴
Swift Package Manager 是管理 Swift 程式套件的工具。你可以把「依賴」理解為專案借用的程式碼功能,例如某個套件提供的資料處理或畫面元件;它不是需要另外安裝到整台電腦的通用命令列工具。
本文聚焦於在 SwiftUI App 專案中加入套件並驗收,不是介紹如何安裝命令列工具。Xcode 提供圖形介面來加入套件,Swift Package Manager 也有自己的依賴管理概念;Apple 的 Swift 套件文件與Swift Package Manager 依賴說明可供你核對基本名詞與流程。
開始操作前,先翻課程說明、專案範本或教師提供的指引,確認需要的是哪個套件、套件來源,以及指定的版本方式。不要看到套件名稱相似就直接加入;來源不同或套件不適用該作業,都可能造成後續無法建置。
課程範本指定版本時,先比較變更風險
Apple 文件列出版本、分支與特定提交等版本要求。它們不是三種可以隨意互換的「最新版」選項:版本規則用來限制套件可採用的版本範圍;分支可能隨套件開發而改變;特定提交則指向某個修訂點。實際可用選項與顯示方式,請以你目前的 Xcode 和課程要求為準。
- 課程範本指定版本或範圍:照範本設定,避免因自行更新而與教師的驗收環境不同。
- 教師指定分支:確認分支名稱和用途,不要用固定版本取代課程指定內容。
- 教師指定提交:核對提交識別資訊;不要只憑套件名稱推測要選哪個修訂點。
- 課程沒有指定規則:先查專案範本與套件說明,再選擇適合課程需求的設定,並記下你採用的方式。
套件已出現,還要把產品加入 App 目標
套件來源、套件產品和專案目標是不同層次。套件來源指出程式碼從哪裡取得;產品是套件中供其他專案使用的部分;目標則是 Xcode 建置的對象,例如你的 SwiftUI App。搜尋得到套件,不代表 App 已經連上所需功能。
依 Apple 的Xcode 套件相依操作說明,加入套件時要確認相依項目與使用目標;若需要調整目標設定,可參考設定 Xcode 專案目標的官方說明。
完成後,回到 Xcode 專案導覽器檢查套件項目與 App 目標設定,確認作業使用的目標包含需要的產品。若程式碼出現無法匯入模組的訊息,先核對產品是否加到正確目標,再檢查來源與版本要求;不要只重複下載套件。
用清單完成加入與建置驗收
按以下順序操作;不同 Xcode 版本的選單文字或畫面可能略有差異,請以目前介面和官方說明為準。
- [ ] 核對課程材料:記下套件名稱或來源,以及教師是否指定版本、分支或提交。
- [ ] 開啟正確專案:在 Xcode 開啟 SwiftUI App 專案,確認不是誤開範本的其他資料夾或目標。
- [ ] 使用套件相依入口:在 Xcode 中加入課程要求的套件來源,並依要求設定版本規則。
- [ ] 選好套件產品:確認要使用的產品已連到 SwiftUI App 的正確專案目標。
- [ ] 檢查套件解析結果:確認 Xcode 能完成套件解析;不要在解析尚未完成時就判定套件可用。
- [ ] 建置並檢查錯誤:建置專案,確認錯誤訊息不是套件解析、目標設定或程式碼本身的問題。
- [ ] 按課程約定處理協作資料:查看專案中的
Package.resolved,並遵守課程或團隊對版本鎖定檔的提交方式。
Package.resolved 用來記錄套件解析結果,協助專案在不同工作環境中維持一致的解析狀態。它不表示所有課程、範本或版本控制流程都必須採用相同的提交策略;先看教師或團隊的規定,再決定如何處理。[Apple 關於套件在 Xcode Cloud 中可用性的文件](https://developer.apple.com/documentation/Xcode/Making-Dependencies-Available-to-Xcode-Cloud)也提醒你,協作或建置流程需要留意依賴如何提供給建置環境。
建置失敗時,按現象分流
先看錯誤發生在套件解析、程式碼匯入,還是建置階段。這些情況成因不同,直接更新版本或刪除專案檔案,可能讓原本可重現的課程設定更難還原。
- 套件仍在解析,或無法取得來源:先確認套件來源是否符合課程資料,並查看 Xcode 顯示的具體錯誤;不要先把所有問題都歸因於網路。
- 套件已出現,程式卻無法使用:檢查產品是否加入正在建置的 App 目標,再核對匯入名稱是否符合套件文件。
- 解析出現版本衝突:回看課程指定的版本規則與範本設定,確認是否有互不相容的要求;不要擅自把指定版本改成最新版。
- 套件能解析但 App 建置失敗:分辨錯誤來自套件、目標設定,還是你自己的 Swift 程式碼。先保留完整錯誤訊息,再依內容檢查。Apple 的常見設定與建置問題說明可作為核對方向。
常見問題:從加入套件到完成作業
Xcode 顯示套件名稱,就表示 SwiftUI App 已經可以使用嗎?
不一定。套件出現在專案中,只表示 Xcode 找到或加入相依項目;你還要確認作業需要的產品已連到正確 App 目標,再檢查程式碼中的匯入方式並建置。若匯入失敗,先看目標設定與產品選擇,不要直接重建整個專案。
課程沒有寫清楚套件版本,我可以選最新版嗎?
先檢查課程範本、教材中的操作畫面和組員使用的設定。如果沒有指定版本,也沒有既有設定,才依套件相容性與作業需求作選擇。你可以記下採用的規則,並在建置後確認專案正常;若課程驗收要求一致,先向教師確認再更新。
使用 Git 協作時,Package.resolved 一定要提交嗎?
不一定,應按課程或團隊慣例處理。這個檔案記錄解析結果,但不同專案的版本控制規則可能不同。先檢查範本和團隊約定;若同學建置後解析出不同結果,對照檔案與套件規則,再確認是否需要統一設定,而不是自行刪除或覆寫。
我只有 Windows 或受限制的學校電腦,怎樣完成 Xcode 設定?
先確認作業是否只要求閱讀文件或提交程式碼,還是明確要求在 Xcode 中加入依賴並建置 App。後者需要可使用 Xcode 的相容 macOS 環境;學校電腦若限制安裝或操作,就不能把「能編輯程式碼」當成已完成驗收。先確認課程是否允許使用遠端 Mac,再安排環境。
沒有可用 Mac 時,先核對作業交付要求
Windows 或學校電腦適合閱讀套件文件、撰寫部分程式碼和整理作業內容,但如果課程要求你在 Xcode 中加入 Swift Package、確認目標並建置 App,這些電腦可能無法完成整個驗收流程。學校設備還可能限制安裝軟體或存取專案;只把程式碼寫好,也不能代替課程要求的 Xcode 建置結果。
先問清楚教師是否允許遠端 macOS 環境,以及作業是否要求特定裝置、模擬器或本機操作。也可以先查看遠端 Mac 學習環境入口,確認使用方式是否符合你的課程規則。Apple 的Xcode 系統需求則可用來核對環境相容性。
如果你只是學 Swift 語法,沒有必要只為一次套件設定改變整套學習安排;若作業確實要求 Xcode 建置,而你暫時沒有合適的 Mac,遠端 Mac 可以作為短期工作環境。相較之下,Windows 無法替你完成 Xcode 專案驗收,受管理的學校電腦可能有權限限制,而臨時更改課程依賴則增加版本不一致風險。先確認課程允許遠端操作、網路連線足以使用,再查看MACGPU 的 Mac 方案資訊是否適合你的作業;若課程要求實體裝置或不允許遠端操作,就應依課程規定另作安排。