iOS 建置突然出現套件解析錯誤，或原本能上傳 TestFlight 的 Archive 在升級後失敗。
最快解法是：不要一次刪除 CocoaPods；先以 Flutter 3.47 的 Swift Package Manager 為主，讓未相容插件回退至 CocoaPods，再於隔離 Mac 完成 Archive 與 TestFlight 驗收。
誰適合採用這套 Flutter 3.47 iOS 依賴遷移流程
這篇文章適合從舊版 Flutter 升級至 3.47、不能承受 iOS 發佈中斷的獨立開發者，以及依賴多個原生插件、尚未確認 Swift Package Manager 相容性的專案維護者。
如果你主要在 Windows 或 Linux 上編寫 Dart 程式碼，也可以把遷移工作拆成「跨平台盤點」與「Mac 上的 iOS 驗收」兩段，避免在唯一一台正式打包機上直接試錯。
提醒：截至 2026 年 9 月 17 日，Flutter 官方穩定文件以 3.47 系列為基線；Swift Package Manager 從 Flutter 3.44 起成為 iOS 與 macOS 原生依賴的預設管理方式，但不代表所有插件已經完成相容。請以Flutter 官方發布說明及遷移文件核對實際行為。
先建立可發佈基線，再開始遷移
Flutter 3.47 iOS 依賴遷移真正危險的地方，不是執行一次指令，而是你可能在沒有回復證據的情況下同時改動 Flutter、Xcode、插件與簽署設定。遷移前應先建立一份只讀紀錄，至少包含以下內容：
| 基線項目 | 應保留的內容 | 失敗時的用途 |
|---|---|---|
| Flutter 工具鏈 | Flutter SDK 版本、Dart 版本與 SDK 路徑 | 還原相同執行環境 |
| 依賴狀態 | pubspec.lock、Podfile、Podfile.lock 與原生 Framework 清單 |
判斷是哪一層改變 |
| Xcode 專案 | 工作區、Build Settings、Scheme 與自訂 Script | 還原 Archive 入口 |
| 發佈證據 | 最近一次成功 Archive、IPA 匯出設定與上傳紀錄 | 確認舊鏈路仍可用 |
| 簽署資料 | Team、憑證類型、Provisioning Profile 名稱 | 避免把簽署問題誤判為依賴問題 |
請在獨立 Git 分支或隔離 Mac 環境執行。正式打包機只保留可發佈分支，不要把「測試 SwiftPM」和「今天要上架的版本」放在同一個工作目錄。
截至上述日期，官方文件仍把未相容依賴的 CocoaPods 回退列為過渡路徑；因此，遷移目標應是「先證明新鏈路可發佈」，不是「先刪乾淨所有 Pod 設定」。你也應留意官方文件列出的 CocoaPods 註冊表只讀時間點為 2026 年 12 月 2 日，但這不等於現有專案會在當天自動失效，插件相容性仍須逐項檢查。Flutter Swift Package Manager 應用開發者文件提供了官方遷移邊界。
第一個工作時段完成插件相容盤點
不要只執行一次 Debug 建置就宣布遷移成功。Debug 可能沒有走完整的 Release 編譯、簽署、Archive 或上傳路徑；你要先從依賴樹與建置紀錄找出所有含有 iOS 原生程式碼的插件。
盤點時可按以下順序進行：
- 檢查
pubspec.yaml與鎖定檔，標示含有 iOS 原生目錄、Swift、Objective-C 或 Framework 的插件。 - 搜尋
ios/Podfile、自訂.podspec、本地 Pod、私有 Spec 及手寫安裝腳本。 - 查看 Xcode 工作區中是否已有以 SwiftPM 加入的套件，以及插件註冊檔是否被重新產生。
- 對每個插件記錄來源、目前管理方式、是否已有官方 SwiftPM 說明、最低 iOS 版本與替代方案。
- 將來源不明的二進位 Framework 單獨列出，因為它可能完全不符合套件管理器的解析方式。
建議先產出一張插件表，而不是直接修改全部依賴：
| 依賴類型 | 目前證據 | 第一選擇 | 回退條件 |
|---|---|---|---|
| 已明確支援 SwiftPM 的插件 | 官方文件或插件自身提供套件設定 | 交由 SwiftPM 解析 | 包解析或編譯失敗 |
| 只有 CocoaPods 設定的插件 | Podspec、Podfile 或安裝腳本 | 暫留 CocoaPods | 官方未提供替代路徑 |
| 本地或私有二進位檔 | 只有 Framework 或自訂 Script | 在隔離環境單獨驗證 | 模組、架構或簽署不符 |
| 來源不明的插件 | 無法確認維護方式 | 暫停遷移並追查 | 找不到可重現來源 |
插件的 iOS 原生整合規則，應以Flutter 插件開發文件中的實際說明為準。社群文章可以協助定位問題，但不能替代你對目前版本與插件來源的核實。
在隔離 Mac 上完成首次 SwiftPM 建置
如果你使用 Windows 或 Linux 開發，可以先在本機完成依賴清單與分支整理，再把已脫敏的專案送到 Mac。專案名稱、Bundle ID、Team ID、憑證名稱與紀錄檔中的 Token 都不應直接貼到共享工作區或支援工單。
以下範例使用佔位符，請在具備專案權限的執行帳號下操作：
# 執行帳號：具備專案讀寫權限的 macOS 使用者
# 專案目錄：/Users/BUILD_USER/Projects/APP_DIR
# Flutter SDK：/Users/BUILD_USER/flutter/bin/flutter
cd /Users/BUILD_USER/Projects/APP_DIR
/Users/BUILD_USER/flutter/bin/flutter --version
xcode-select -p
git status --short
/Users/BUILD_USER/flutter/bin/flutter pub get
/Users/BUILD_USER/flutter/bin/flutter build ios --config-only --no-codesign
預期先看到 Flutter 版本、Xcode Command Line Tools 路徑、乾淨或可解釋的 Git 狀態，接著完成 Dart 依賴取得與未簽署 iOS 設定產生。不要在這個階段直接上傳商店。
若要撤銷，先保存 git diff 與建置紀錄，再執行：
git restore -- ios Podfile Podfile.lock
git switch production-safe
這裡的 production-safe 只是你的舊版可發佈分支名稱，請改成實際分支。不要使用沒有確認內容的 git clean -fd，它可能刪除尚未提交的本地插件或測試資料。
首次建置要觀察三類證據：SwiftPM 是否完成套件解析、插件註冊是否仍存在，以及編譯階段是否出現模組找不到或最低系統版本衝突。只有無簽署建置成功，才可以進入 Release 與 Archive 驗證。
雙軌依賴的衝突處理與評分
SwiftPM 與 CocoaPods 可以在過渡期共同存在，但共同存在不等於同一個原生依賴可以安裝兩次。最常見的判斷方式，是把錯誤訊息和負責管理的依賴對應起來：
| 可見現象 | 優先判斷 | 處理方向 | 編輯評分 |
|---|---|---|---|
| Duplicate symbols 或重複 Framework | 同一依賴被兩條鏈路引入 | 只保留一個來源，再清理工作區重建 | ★★★★★ |
| Module not found | 插件註冊或搜尋路徑不完整 | 回到該插件的管理方式，暫時保留 CocoaPods | ★★★★☆ |
| 最低系統版本衝突 | 套件要求與專案設定不一致 | 逐項對齊部署目標，不要一次提高全專案 | ★★★★☆ |
| 遠端套件下載失敗 | 連線、快取或套件來源不穩定 | 先驗證乾淨解析，再恢復可重現來源 | ★★★☆☆ |
| 只有某個插件在 Release 失敗 | Debug 沒涵蓋其編譯路徑 | 保留舊鏈路並對該插件做獨立替代評估 | ★★★★★ |
這個評分是遷移風險的編輯判斷，不是建置速度或相容率的實測。不要為了「全 SwiftPM」而直接修改第三方插件原始碼；那會讓日後升級、回復及責任追查更加困難。若插件沒有官方支援，就先留在 CocoaPods，並在插件更新或下一次 Flutter 版本複核時再評估。
把遠端 Mac 與 CI 固定成可重現環境
遠端 Mac 的價值不只是讓你可以開啟 Xcode，而是把依賴遷移從唯一生產機隔離出來。你應固定以下項目：
- Flutter SDK 的實際路徑，不要依賴互動終端的模糊
PATH。 - Xcode 版本與
xcode-select指向，互動工作階段與無人值守任務要一致。 pubspec.lock、Podfile.lock 與 SwiftPM 解析結果。- 建置執行帳號、專案工作目錄及輸出資料夾。
- 憑證、私鑰、Provisioning Profile 與 App Store Connect 憑證的存取權限。
SwiftPM 快取只能用來縮短重複解析時間，不能當成成功條件。至少要做一次乾淨環境解析，確認沒有快取時仍能取得所需套件。依賴快取也不應和簽署私鑰放在同一個可下載目錄，遠端連線中斷後，應記錄工作階段狀態、最後一個成功指令與可安全重跑的步驟。
如果你需要在遠端 Mac 上執行這種隔離建置，應先查看 SSHMac 的幫助中心，確認連線、帳號權限與工作階段恢復方式；這些操作條件和 Flutter 本身的插件相容性是兩個不同問題，不要混在同一份故障紀錄中。
用 Archive 與 TestFlight 決定是否正式切換
無簽署建置成功後，仍要按發佈順序驗證：
- 使用 Release 設定編譯，確認原生插件在實際模式下能完成連結。
- 在 Xcode 中建立 Archive，檢查簽署團隊、Bundle ID、版本號與建置號。
- 匯出 IPA，確認輸出方式與目前的發佈憑證一致。
- 上傳至 App Store Connect，觀察處理狀態，而不是只看本地指令是否結束。
- 透過 TestFlight 安裝，重新測試登入、推播、付款、相機或其他由原生插件負責的功能。
- 保留舊依賴鏈路的可發佈節點，直到新鏈路通過真實裝置安裝與關鍵流程驗證。
Flutter 的 iOS 發佈文件涵蓋建置與簽署流程，可參考官方 iOS 建置發布指南。上傳後的處理狀態則要按照 Apple 的建置狀態說明判讀；「已上傳」不代表已可供 TestFlight 測試。
| 驗收階段 | 通過證據 | 不通過時的回退 |
|---|---|---|
| Release 編譯 | 無模組、連結或插件註冊錯誤 | 回到插件相容表逐項隔離 |
| Archive | 產生可簽署的 Archive，設定與舊鏈路可比較 | 切回舊分支，不改生產機 |
| IPA 匯出 | 匯出方式、Team 與憑證符合發佈要求 | 還原簽署設定並重新檢查權限 |
| App Store Connect | Apple 接受上傳並進入處理流程 | 依處理狀態分類，不先重做依賴 |
| TestFlight | 真實測試裝置能安裝且原生功能正常 | 保留 CocoaPods 鏈路，暫緩切換 |
Apple 的上傳建置規則及App Store Connect 工作流程應與團隊的發佈紀錄一併保存。若新鏈路只通過本地 Archive、未通過 TestFlight，就不能視為完成遷移。
用條件分支決定最後方案
- 若所有原生插件都有可核實的 SwiftPM 路徑，乾淨解析、Release、Archive 與 TestFlight 都成功，則可以安排完全切換。
- 若只有部分插件相容，且 SwiftPM 與 CocoaPods 沒有重複引入同一依賴，則保留雙軌，並記錄每個插件的複核條件。
- 若某個插件仍只能使用 CocoaPods，但舊鏈路可以穩定發佈，則不要為追求純 SwiftPM 而冒險，先保留 CocoaPods。
- 若Archive 或 TestFlight 失敗，則回到最後一個可發佈節點，還原鎖定檔與工作區，再針對單一插件重做驗證。
- 若你只有一台生產 Mac，或主要在 Windows、Linux 上工作，則先準備隔離的遠端 Mac，等新舊鏈路都完成 TestFlight 驗收後再決定是否長期保留。
這套分支比「遷移成功或失敗」更適合獨立開發者，因為雙軌本身可以是合格的中間狀態，而不是必須立刻消除的技術債。
FAQ：遷移時最容易忽略的判斷
Flutter 3.47 升級後，為什麼 iOS 專案檔案會自己變更？
從 Flutter 3.44 起，Swift Package Manager 已成為 iOS 與 macOS 原生依賴的預設管理方式。升級或重新取得依賴時，Flutter 可能更新 Xcode 工作區、套件解析資訊與插件註冊內容；先在分支中比對變更，並保留舊版依賴鎖定檔與最近一次成功 Archive，才能判斷哪些修改可接受。
Flutter 插件還不支援 Swift Package Manager，應該怎麼處理？
不要為了追求純 SwiftPM 而直接修改第三方插件原始碼。先確認插件是否含有 iOS 原生程式碼、手寫 Podfile 設定或本地 Framework；若官方尚未提供 SwiftPM 支援，就讓該插件暫時回退至 CocoaPods，或在獨立分支評估替代插件，並用 Archive 與 TestFlight 驗證後再決定。
Flutter 專案可以同時使用 SwiftPM 和 CocoaPods 嗎？
可以，但前提是兩套管理方式負責不同的原生依賴，不能讓同一個 Framework 或模組被重複引入。雙軌期間要檢查重複符號、模組找不到、最低系統版本衝突與套件解析失敗；只要出現責任歸屬不清，就應先回到可發佈的 CocoaPods 鏈路。
SwiftPM 遷移後 iOS Archive 失敗，要怎樣安全回復？
先停止修改生產建置機，切換至遷移前分支，還原依賴鎖定檔、工作區與原有 CocoaPods 設定，再使用相同的簽署方式重新 Archive。若舊鏈路能產生可上傳的 IPA，先保留該發佈節點；新鏈路必須完成真實 TestFlight 安裝及原生功能驗證，才可重新安排切換。
使用 Windows 開發 Flutter，要如何驗證 iOS 依賴遷移？
Windows 可負責 Dart 程式碼與依賴盤點，但 iOS 的 SwiftPM 解析、Xcode 建置、簽署、Archive 和 App Store Connect 上傳仍要在 macOS 完成。你可以把專案分支與鎖定檔送到隔離的遠端 Mac，以 SSH 或網頁控制台執行無簽署建置，再由具備憑證的環境完成發佈驗收。
如果你目前只有一台生產 Mac，直接在上面測試 Flutter 3.47 會把依賴風險、簽署風險與發佈中斷綁在一起；若主要使用 Windows 或 Linux，還會多出遠端連線與工具鏈不一致的問題。自購 Mac 適合長期固定重負載、需要實體介面或必須完全自行管理硬體的人，但為一次遷移而添置設備，成本與維護責任未必合理。對需要短期建立隔離環境的情況，租用 SSHMac 的遠端 Mac，先完成雙軌建置、Archive 與 TestFlight 驗收，再決定是否長期保留，通常更容易控制變更範圍；你可先從SSHMac 的服務入口了解可用方式。