Flutter 3.47 iOS 建置失敗，最快的處理順序是：先升級到包含相關 iOS 與 SwiftPM 修復的最新 3.47 穩定補丁版，再用同一提交重跑依賴解析、Build 與 Archive；仍然失敗時，才按專案類型檢查 SwiftPM 集成和插件支援，只有插件不相容才暫時回退 CocoaPods。
這篇適合剛升級 Flutter 3.47、發現原本正常的 iOS 專案無法建置或歸檔的獨立開發者。若你使用 Xcode 27、遠端 Mac 或無人值守打包，也能用同一套流程區分專案故障與環境故障。
最後更新於 2026 年 9 月 16 日。 Xcode 27 已於 2026 年 9 月 14 日正式發布；日期與版本狀態請以 Apple 的 Xcode 發布資料及 Xcode Release Notes 為準。
先保存失敗現場，再動任何設定
典型的脫敏對照日誌會是：
同一提交：
舊 Flutter／Xcode 環境：依賴解析成功，Debug Build 成功
升級 Flutter 3.47 與 Xcode 27 後：Swift package 解析或 Xcode Build 失敗
這個對照只能說明升級後出現關聯，不代表所有 Flutter 3.47 iOS 建置失敗都由同一個回歸造成。你應先保存以下資料：
- 實際 Flutter 補丁版本、Xcode 版本與目前使用的 SDK。
- 觸發方式：
flutter build ios、Xcode 圖形介面、xcodebuild、CI 或 SSH。 - 第一個有效錯誤，而不是最後一行泛用的
build failed。 - 依賴解析結果、普通 Build 結果，以及 Archive 結果。
- 專案提交、插件鎖定檔、
Podfile.lock和 Package 解析狀態。
| 要保存的證據 | 你要回答的問題 | 不要先做的事 |
|---|---|---|
| Flutter 與 Xcode 版本 | 故障是否在工具鏈切換後出現？ | 不要先重建整台打包機 |
| SwiftPM／Pods 解析輸出 | 失敗發生在依賴解析還是編譯？ | 不要先刪除全部快取 |
| Debug、Release、Archive 結果 | 是普通建置問題還是發布鏈路問題？ | 不要只保留最後一行錯誤 |
| 本地與遠端命令列記錄 | 是專案問題還是執行環境問題？ | 不要把遠端失敗直接歸因於 Flutter |
先把 Flutter 3.47 補丁版本收斂
截至 2026 年 9 月 16 日，Flutter 官方 changelog 已把「啟用 SwiftPM 時的 iOS／macOS 建置失敗」列入 Flutter 3.47.2 修復項，也列出原生 iOS Add-to-App 專案在 Xcode 27 下建置 Flutter Swift packages 的相關修復，並繼續列出後續 3.47.3。請直接對照 Flutter 官方 changelog，不要把 3.47.0、3.47.1 與後續補丁視為同一環境。
Xcode 27 的發布狀態則以 Apple 的 Xcode 27 工具說明為準。修復時保持以下變數不變：
- 在獨立分支或可回退環境確認目前 Flutter stable 補丁。
- 升級到官方已包含相關修復的最新 3.47 補丁。
- 保留專案原始碼、插件鎖定檔與建置命令。
- 先重跑依賴解析，再執行普通 Debug Build。
- 最後執行 Release Build 和 Archive。
- 把升級前後的第一個有效錯誤並排保存。
| 版本狀態 | 建議動作 | 判斷結果 |
|---|---|---|
| 早於官方修復補丁 | 先升級到最新穩定 3.47 補丁 | 先排除已知回歸 |
| 已在修復補丁仍失敗 | 檢查 SwiftPM 集成、插件與 Target | 轉入專案結構排查 |
| 使用後續 3.47 補丁 | 重新記錄最小專案與真實插件專案結果 | 不把舊錯誤直接套用 |
| 升級後只有遠端失敗 | 對比本地與遠端工具鏈、權限和會話 | 轉查環境差異 |
按專案類型檢查 SwiftPM 集成
Flutter 官方的 Swift Package Manager 集成文件是檢查入口。你要確認專案是否存在 FlutterGeneratedPluginSwiftPackage、建置前置腳本是否正常，以及正確的 Target 是否依賴對應 package product。
不要把三種專案混在一起處理：
- 普通 Flutter App：先看生成的 Swift package、插件解析及 Runner Target。
- 原生 iOS Add-to-App：除了宿主專案，還要核對 Flutter module 與原生 Target 的接入方式；可參考 Add-to-App 官方文件。
- 自訂 Target 或多環境專案：確認每個 Target 是否都加入正確依賴，不能只在 Debug Target 修好後就宣告完成。
Swift Package Manager 的解析成功，不等於 Xcode 編譯一定成功。依次區分：
- 依賴解析失敗：看 package identity、版本、Git 存取與解析記錄。
- Xcode Build 失敗：看 Target 依賴、模組匯入和插件原生程式碼。
- Archive 失敗：看 Release 設定、簽名、匯出選項和打包腳本。
- 上傳失敗：看產物、權限與 App Store Connect 流程。
提醒： 重置 Package Cache 會讓你失去部分現場證據。只有在已保存解析輸出、確認快取損壞，並且有明確回退方法時，才把它列入後續動作。
只在插件不相容時建立 CocoaPods 回退
Flutter 3.47 的 SwiftPM 路徑是否可用，還取決於插件和私有原生依賴。逐項核對：
- 插件是否明確支援 SwiftPM。
- 是否仍有插件只能透過 CocoaPods 整合。
Podfile是否被手動修改過。- 私有原生套件是否要求特定最低系統版本。
- Flutter 是否因插件不相容而回到 CocoaPods。
- 目前建置是否仍然讀取
Podfile.lock或 Pods 目錄。
| 依賴情況 | 建議路徑 | 回退條件 |
|---|---|---|
| 所有插件均支援 SwiftPM | 保持 SwiftPM，修正 Target 與生成檔 | 不要為了習慣改回 Pods |
| 單一插件尚未支援 SwiftPM | 暫時保留 CocoaPods | 插件完成相容後再重測 |
| SwiftPM 與 Pods 同時存在 | 先畫出實際依賴鏈 | 不要盲目刪除其中一條 |
| 私有套件解析失敗 | 先核對來源、權限和版本 | 有可驗證替代來源才回退 |
回退時要先建立可撤銷變更。保存原始 Podfile、鎖定檔和建置命令，標記哪些插件使用 Pods，並在獨立分支完成一次 Debug、Release 與 Archive。這不是 SwiftPM 與 CocoaPods 的功能選型比較，而是為了讓發布鏈路先恢復，同時保留日後移除回退的路徑。
用 Archive 驗收，而不是只看 Debug Build
首次 Build 成功後，按以下順序復測：
- 以同一提交執行依賴解析。
- 以同一 Target 執行 Debug Build。
- 切換 Release 設定執行建置。
- 執行 Archive，保存
.xcarchive結果。 - 執行匯出，核對簽名與匯出設定。
- 在必要時完成上傳前檢查。
- 以圖形會話與 SSH／CI 各跑一次。
- 若只有遠端失敗，再檢查工具鏈選擇、工作目錄權限、憑證會話和快取歸屬。
本地能打包、遠端 Mac 失敗時，先不要改程式碼。比較兩邊的 flutter doctor、Xcode 路徑、環境變數、執行使用者、Keychain 解鎖狀態和工作目錄。遠端無人值守工作還要檢查登入會話是否真的能讀取簽名資料；圖形介面成功不代表 SSH 服務程序擁有相同權限。
| 驗收階段 | 必須看到的結果 | 失敗時歸類 |
|---|---|---|
| 依賴解析 | package、插件與鎖定版本一致 | SwiftPM／Pods 或來源問題 |
| Debug Build | 開發建置完成 | Target 或原生編譯問題 |
| Release Build | 發布設定可編譯 | 編譯旗標或配置問題 |
| Archive | 產生可檢查的封存產物 | Release、簽名或腳本問題 |
| 匯出／上傳前 | 產物與簽名符合發布要求 | 匯出設定或憑證權限問題 |
把修復結果固化到遠端打包環境
如果你需要遠端 Mac 作為長駐 iOS 打包環境，第一週不要急著切換生產主機。先固定 Flutter 補丁、Xcode、依賴鎖定檔與建置入口，並保留一組最小回歸任務。
- [ ] 為 Flutter、Xcode、插件與 SwiftPM／Pods 狀態建立版本記錄。
- [ ] 讓最小 Flutter 專案完成依賴解析、Build 和 Archive。
- [ ] 讓包含真實插件的脫敏專案重跑相同流程。
- [ ] 測試 SSH 或 CI 執行時的目錄、Keychain 和憑證權限。
- [ ] 斷線重連後重新執行一次發布建置。
- [ ] 主機重啟後確認工具鏈路徑和快取歸屬沒有改變。
- [ ] 為每次 Flutter 或 Xcode 更新保留可回退環境。
- [ ] 只有在兩條環境都可驗收後，才決定是否移除舊工具鏈。
若你需要同時保留舊版與新版 Flutter／Xcode，或主要開發電腦是 Windows、Linux，無法獨立完成 Archive，可以先查看 MACCOME 的遠端 Mac 方案。先用真實發布任務驗證工具鏈，再決定是否長期保留；需要了解服務入口時，也可從 MACCOME 繁體中文首頁查看可用方案。
本地方案的問題通常是要自行維護常駐 Mac、承擔硬體閒置與升級衝突，還要處理斷線後無法取用的打包環境；雲端 CI 則可能讓你失去完整的圖形化 Xcode 診斷入口，並受限於預設工具鏈與快取策略。若你的需求是短期驗證 Flutter 3.47、並行保留兩套 Xcode，或讓 Windows／Linux 工作站完成遠端 Archive，租用 MACCOME 的 Mac 會比臨時購置一台專用打包機更容易先驗證，再決定長期架構。