Flutter 官方將 Flutter 3.44 起的 Swift Package Manager（SwiftPM）列為 iOS 與 macOS 依賴管理的預設方式；但預設不代表每個既有專案都已完成切換。官方 SwiftPM 文件 因此，Flutter 3.47 iOS CI 應按專案場景分批驗收：先確認插件實際走 SwiftPM 或 CocoaPods 回退，再在乾淨的 Mac CI 環境驗證解析、建置與歸檔；不要只憑本機成功就全量切換。Flutter 3.47 穩定版發布說明
適合 Flutter iOS 應用維護者：升級 Flutter 3.47 前，想確認既有插件和原生依賴是否適用 SwiftPM。
適合 CI 與 DevOps 工程師：需要核對 Mac 建置節點上的依賴解析、歸檔及簽署證據。
適合 Flutter 插件維護者：要判斷套件是否支援 SwiftPM，或是否仍須保留 CocoaPods 路徑。
最後更新於 2026 年 10 月 31 日；版本與遷移安排核對自 Flutter 官方 SwiftPM 文件，CI 流程參考 Apple Swift Package Manager 持續整合指南。
從一般 Flutter iOS 應用確認目前依賴路徑
不要先把「Flutter 3.47」等同於「這個專案已使用 SwiftPM」。Flutter 官方說明預設依賴管理方式自 Flutter 3.44 起改為 SwiftPM，但專案是否已採用、遷移是否完成，仍須以實際設定和建置結果確認。Flutter iOS SwiftPM 文件
| 專案線索 | 驗收時要確認 | 可接受的結果 |
|---|---|---|
| Flutter iOS 應用 | 檢視專案整合設定、套件解析紀錄及建置日誌 | 能指出目前實際使用 SwiftPM，或明確說明仍有 CocoaPods 路徑 |
| Flutter 插件 | 查看插件文件與作者提供的 SwiftPM 支援資訊 | 相依套件和原生程式碼均能依預期解析、建置 |
| 原生 iOS 工程嵌入 Flutter 模組 | 以宿主工程的建置入口檢查依賴解析和整合方式 | 宿主工程與 Flutter 模組各自的依賴責任清楚，建置結果可重現 |
遷移文件描述的是官方支援的工作流程，不能代替團隊對舊專案設定的稽核。請將自動遷移或工具執行的結果，與團隊手動修改的設定分開記錄；如果不確定某個檔案是由工具更新還是由工程師調整，先比較版本控制中的變更，再判斷是否需要保留。
提醒：不要只以是否存在
Package.resolved作為 SwiftPM 已正常運作的唯一證明。還要核對本次 CI 是否真正解析到預期套件，並確認鎖定狀態與提交一致。
依插件支援情況處理 SwiftPM 與 CocoaPods
Flutter 專案的依賴鏈不是只由應用本身決定：插件可能提供 SwiftPM 支援，也可能仍依賴 CocoaPods。Flutter 官方文件提及，不支援 SwiftPM 的插件可以回退至 CocoaPods；實際建置是否成功，仍須按插件文件和 CI 輸出判斷。Flutter 插件 SwiftPM 說明
| 插件與依賴狀態 | 驗收動作 | 切換判斷 |
|---|---|---|
| 插件有明確 SwiftPM 支援 | 核對插件宣告、解析出的套件與鎖定檔，並在乾淨環境建置 | 解析和建置均可重現，才納入 SwiftPM 切換 |
| 插件仍依賴 CocoaPods | 查閱插件維護者文件，檢查 CLI 與 CI 日誌中的實際回退路徑 | 回退成功且可追蹤，可暫時保留；若依賴路徑不明，先隔離問題 |
| 插件狀態不明或有原生修改 | 確認原生目標、套件來源及修改方式，再用同一提交重建 | 取得足夠證據前，不把它標為相容 |
插件作者提供的支援狀態，是評估入口而不是最終驗收。Flutter 的插件開發文件可協助確認插件自身的整合方式；團隊還應在 CI 輸出中記下實際解析的依賴、採用的管理器，以及是否發生 CocoaPods 回退。若建置通過但走的是回退路徑，結論應寫成「目前依賴 CocoaPods 路徑可建置」，而不是「插件已通過 SwiftPM 驗收」。
按 add-to-app 宿主工程驗收整合邊界
將 Flutter 模組嵌入既有 iOS 工程時，驗收對象不是一般 Flutter iOS 應用的單一建置入口，而是宿主工程如何取得並整合 Flutter 模組。應依照 Flutter 的現有 iOS 工程整合指南，核對宿主專案設定、依賴解析方式與實際建置入口。
先在版本控制中檢視舊 CocoaPods 整合留下的設定，並按官方遷移文件確認哪些內容應清理；不要看到 SwiftPM 相關設定後，就自行刪除所有 Pods 設定。若同一宿主工程還有其他原生依賴使用 CocoaPods，清理範圍應限定在已確認的 Flutter 整合部分。
遷移後，使用宿主工程的正式建置命令重新解析依賴、執行測試並產生歸檔。只有 Flutter 模組單獨建置成功，不能證明宿主工程能完成簽署和交付；反過來，宿主工程沿用既有快取成功，也不足以證明乾淨環境可重現。
在 Mac CI 取得乾淨解析與簽署證據
乾淨環境的驗收目的，是排除本機快取掩蓋缺失依賴的可能。選用與日常 CI 相符的 Mac 節點，以同一提交執行依賴解析與建置，並保留解析輸出、鎖定檔差異和建置日誌。Apple 的 Swift 套件 CI 文件可作為套件解析與 CI 工作流程的依據。
建議用以下可勾選項目整理驗收紀錄：
- [ ] 記錄 Flutter、Xcode 與建置節點環境，並將它們與本次提交關聯；版本或環境變更時，重新核對結果。
- [ ] 在不沿用開發者本機快取的條件下，重新取得 Swift Package Manager 依賴；保存解析日誌，檢查鎖定檔是否有非預期變更。
- [ ] 確認私有套件或 Git 依賴可由 CI 取得；檢查憑證授權範圍、Git 工具設定與存取錯誤，不得把密鑰輸出至日誌。
- [ ] 以 CI 正式採用的建置入口執行測試和 Xcode 建置；明確記錄插件是否走 SwiftPM，或發生 CocoaPods 回退。
- [ ] 執行歸檔及匯出，保存建置結果、簽章相關日誌與交付產物；依 Flutter 的iOS 發布文件核對發布流程，不以測試通過代替歸檔驗收。
- [ ] 在相同提交的乾淨建置中重複關鍵流程；如果解析結果、依賴管理路徑或簽署結果不一致，先停止擴大遷移並查明差異。
憑證提醒：CI 必須能存取私有依賴，不代表可以把金鑰或存取權杖寫入建置腳本、版本庫或公開日誌。請使用 CI 的機密管理方式提供憑證，並把授權限制在建置需要的範圍。
依驗收結果決定切換、保留回退或暫緩
以下條件分支可用來形成可稽核的決策，而非只依賴個人經驗判斷：
- 若應用和所有關鍵插件均有明確 SwiftPM 支援，乾淨 Mac CI 能穩定解析依賴，且測試、建置、歸檔與簽署均有可追溯證據，則切換該專案的依賴路徑，並將這次驗收結果納入版本升級紀錄。
- 若只有少數插件仍依賴 CocoaPods，且 CI 日誌能證明其回退路徑可用，則先保留必要的回退，對已驗證的部分逐步切換；每次插件或依賴更新後重跑相關驗收。
- 若插件支援狀態不明、乾淨環境解析失敗、鎖定檔出現無法解釋的差異，或歸檔與簽署尚未驗證，則暫緩遷移，先補齊證據再評估。
- 若專案採用 add-to-app，則以宿主工程的建置與交付結果為準，不以一般 Flutter iOS 應用的驗收結論代替。
CocoaPods 倉庫狀態也應列入後續風險追蹤，但不可把預定安排寫成已發生事件。Flutter 官方文件將 CocoaPods 倉庫轉為唯讀的日期列為 2026 年 12 月 2 日；截至本文核對日期，這是官方安排，並非已生效的狀態。Flutter SwiftPM 應用文件 建議在內部遷移紀錄中保留這項時間安排，並於日期接近或官方文件更新時再次確認；它不應取代當下對插件相容性與建置結果的檢查。
若團隊目前缺少可用的 Mac 建置環境，先為代表性專案準備能執行依賴解析、測試和歸檔的節點，再擴大遷移，比在沒有交付證據時直接切換更容易控制風險。短期驗收可比較自備 Mac 與遠端 Mac 的管理成本、權限需求和使用週期；若需要臨時或按期使用，可先查看 RUVCLOUD 的遠端 Mac 開發與 CI 環境及租用方案與價格。但若工作負載長期穩定且持續繁重，或必須直接連接特定實體裝置與介面，自購 Mac 可能更合適；選擇遠端環境時，仍應先驗證該節點能否支援團隊實際的 Xcode、依賴和簽署流程。