最後更新於 2026 年 8 月 21 日；版本狀態核對自 Flutter 官方穩定版發布索引、依賴指南與 Apple 官方 Xcode 文件。

本週不要在生產建置節點直接覆蓋升級，也不要一次刪除 CocoaPods 設定；應先在隔離的遠端 Mac 升級 Flutter 3.47，保留尚未相容外掛的回退路徑，完成真機、Archive、簽署與 CI 驗收後，才切換主節點。這套做法適用於含原生 iOS 外掛、Flavor、自訂 Target 或 add-to-app 整合的 Flutter 專案。

維護原生依賴的 Flutter 開發者，可藉此判斷 SPM 與 CocoaPods 應如何共存。負責遠端 Mac 建置節點的 DevOps 工程師，則可用同一份清單建立可重現的升級、快取與回滾流程。

01

版本事實與遷移邊界

截至 2026 年 8 月 21 日，Flutter 官方發布索引將 3.47 列為穩定版本；Flutter 官方亦確認，從 3.44 起，iOS 與 macOS 原生依賴預設使用 Swift Package Manager。對尚未支援 SPM 的依賴，Flutter 仍保留 CocoaPods 回退機制，這代表「預設方式改變」並不等於「現有 Podfile 必須立即刪除」。

CocoaPods 及其註冊表於 2026 年 12 月 2 日永久轉為唯讀的官方安排屬於維護規劃資訊，但不能直接推導出某個 Flutter 外掛的相容性。外掛是否能以 SPM 解析、是否產生正確的原生編譯產物，以及是否符合專案的最低系統要求，仍要按實際專案測試。

升級前先保存以下證據：

  • pubspec.lock、原有 Podfile、Podfile.lock 與 Xcode 專案檔。
  • 所有可用 Scheme、Build Configuration 及自訂 Target 的設定差異。
  • 最近一次成功的測試、Archive、簽署與導出日誌。
  • 目前 CI 使用的 Flutter、Xcode、Ruby、CocoaPods、憑證及環境變數來源。
  • 可重新建立的舊版遠端 Mac 節點或映像，避免回滾時只剩未驗證的備份。
02

專案形態分流

先判斷工程結構，再選擇遷移策略；不要把所有 Flutter iOS 專案都當成預設模板處理。

專案形態 主要觀察項目 首選處理 不應直接做的事
接近預設模板 是否有原生改造、外掛與自訂 Target 先讓預設 SPM 流程產生變更，再逐項驗收 手動照抄 Xcode 設定
仍有 CocoaPods 外掛 每個外掛的解析來源與原生產物 保留雙軌，或逐項替換 因 Podfile 存在便判定升級失敗
多 Flavor／自訂 Target Scheme、Build Configuration、準備指令碼 每個組合分別測試與封存 只驗證 Runner Debug
add-to-app 原生主工程、模組初始化、資源打包 先核對嵌入方式，再測原生啟動 未核對便疊加新舊整合
遠端 Mac／CI 節點 SSH 環境、憑證、快取、重啟後狀態 以隔離節點重現完整流水線 只在圖形工作階段測試成功

對於缺少備用 Mac 的團隊，可先參考 NodeMini 的遠端 Mac 方案，將它視為隔離遷移節點，而不是未驗證便取代生產主機的理由。

03

標準 Flutter iOS 專案

標準專案的重點不是手工重建每一項 Xcode 設定，而是觀察升級工具實際修改了哪些檔案，並確保版本控制差異可解釋。

先在複製的工作目錄執行：

flutter --version
flutter pub get
git status --short
git diff -- ios

若升級程序需要重新產生 iOS 工程檔，應先建立獨立分支，再比較 ios/ 內的專案檔、依賴宣告、Flutter 框架準備指令碼與共享 Scheme。生成檔案是否提交，必須按照專案原有規範處理；不能因為檔案由工具產生，便一律忽略，也不能把整個目錄無差別提交。

驗收至少包括：

  • 模擬器啟動，確認 Swift 包解析與 Flutter 框架準備流程完整。
  • 真機建置，確認簽署身份、Provisioning Profile 與原生外掛能共同編譯。
  • Release Archive 及導出，確認產物路徑與 CI 使用的設定一致。
  • 將升級前後 git diff、建置日誌及產物雜湊保存，讓日後能定位是依賴變更還是環境變更。

提醒： 模擬器可執行只證明部分編譯路徑成立；它不能證明真機簽署、Distribution Archive 或非互動式 CI 工作階段也能完成。

04

CocoaPods 混合依賴

Flutter iOS 專案仍可能同時出現 Swift Package Manager 與 CocoaPods。真正需要判斷的不是「是否還有 Podfile」，而是每一個原生外掛實際由哪一套方式解析，以及最後是否產出可用的連結結果。

建議建立一份外掛盤點表，至少記錄：

  • 外掛名稱、版本鎖定位置及原生平台。
  • 依賴來源是 SPM、CocoaPods，或由 Flutter 依賴機制觸發回退。
  • 解析後的版本、編譯產物與最低系統要求。
  • 模擬器、真機和 Release Archive 的結果。
  • 若移除該外掛，是否有替代套件或可恢復的舊整合分支。

若全部必要外掛均能以 SPM 解析，且真機與 Archive 通過，可考慮逐步減少 CocoaPods 依賴；若只有部分外掛支援，則保留雙軌比強行清理更安全。若某個關鍵外掛在真機或封存階段失敗，應先替換外掛或暫緩升級，而不是把錯誤歸因於 Xcode 快取。

05

Flavor 與自訂 Target

多配置專案最容易出現「預設 Runner 成功、production 無法封存」的假成功。每一個 Flavor 都應對應到清楚的 Scheme、Build Configuration、Bundle Identifier、簽署設定及原生準備指令碼；任何一項只在 Debug 生效，都不能視為發布流程完成。

在隔離節點逐一執行相同任務：

flutter test
flutter build ios --release
xcodebuild -list
xcodebuild -showBuildSettings

實際指令應按照專案的 Workspace、Scheme 與簽署方式補上必要參數。驗收證據要包含 Scheme 設定、完整建置日誌、Archive 位置和導出結果，而不是只截取最後一行成功訊息。

決策條件如下：

  • 若每個 Flavor 的測試、Release Archive、簽署與導出均通過，則可把遷移提交至候選 CI 節點。
  • 若只有 staging 通過、production 失敗，則回退到舊依賴流程，先修正該 Flavor 的原生設定。
  • 若自訂 Target 找不到生成的 Swift 包，則檢查 Target membership、Build Phases 和配置繼承，不要直接複製 Runner 設定。
  • 若本地圖形介面通過但 SSH 失敗，則先修復非互動式環境，再判定節點可用。
  • 若無法在限定時間內重現舊版產物，則暫停生產切換，補足鎖定檔、憑證與節點回復演練。
06

add-to-app 原生主工程

add-to-app 不能套用純 Flutter App 的遷移假設。原生 iOS 主工程可能已經管理包依賴、資源、啟動流程和多個配置；舊有嵌入 Framework 或 CocoaPods 方式若與新整合直接疊加，可能造成重複連結、資源遺漏或模組初始化順序錯誤。

依照 Flutter add-to-app iOS 維護指南核對：

  • 原生頁面啟動 Flutter 模組時，模組初始化是否仍在正確位置。
  • Flutter 產物、資源與原生主工程的打包邊界。
  • Debug、Staging、Release 是否使用相同且正確的模組依賴。
  • 原生主工程現有的 SPM 或 CocoaPods 依賴是否與 Flutter 模組重疊。
  • 舊整合是否能在獨立分支中恢復，並成功啟動原生頁面。

至少完成一次原生頁面啟動 Flutter 模組、一次 Release 建置，以及一次舊整合恢復演練。Apple 的 Xcode 發布流程文件可作為測試與發佈階段的驗收依據；Archive 與導出則應對照 Apple 的封存與導出說明。

07

遠端 Mac 與 CI 節點

遠端 Mac 的驗收目標不是證明某次 SSH 指令能執行，而是證明節點在沒有圖形登入、快取不存在或主機重啟後，仍能重現同一個 Flutter iOS 流程。這也是遠端 Mac 開發環境與臨時手動測試機之間最重要的差別。

先固定並記錄：

  • Flutter SDK、Xcode 與套件鎖定狀態。
  • 工作目錄、DerivedData、依賴快取及清理策略。
  • SSH 非互動工作階段能取得的 PATH、環境變數和憑證代理。
  • 簽署憑證與 Provisioning Profile 的保存方式、權限及到期處理。
  • 節點重啟後，CI Runner、快取目錄與必要服務是否能恢復。

可把驗收分成乾淨建置、快取建置、真機簽署、Archive、導出及重啟後重跑。每項都應保存退出狀態、完整日誌、產物路徑和失敗原因。簽署身份管理可參考 Apple 的團隊簽署憑證文件，不要把個人圖形工作階段中的鑰匙圈狀態，誤當成 CI 節點已完成設定。

完成後建立一份遷移紀錄：選擇「升級並切換」、「繼續 SPM／CocoaPods 雙軌」或「回滾並暫緩」。紀錄必須附上專案形態、依賴來源、各 Flavor 結果、Archive 與簽署證據，以及回復舊節點的實際步驟。

08

常見問題

FAQ 已放在此處，方便需要快速判斷的工程師直接定位依賴、Flavor、add-to-app 與遠端節點的處理方式。

09

生產切換與遠端 Mac 選擇

當隔離節點完成所有驗收後，才適合安排生產切換窗口；切換前保留舊節點、舊鎖定檔與可恢復的 CI 設定，並先讓一個非關鍵流水線走完整流程。若團隊目前使用單一本地 Mac，常見缺點是無法與日常開發隔離、重啟或憑證變更會中斷工作，而且難以讓 CI 長時間穩定重現。

若沒有備用 Mac，可先使用 NodeMini 的遠端 Mac 租賃方案準備一個獨立節點，複製現有 Flutter iOS 流水線，完成一個發布週期的遷移驗收後，再決定長期保留、擴充或釋放。對需要實體真機長時間連線的團隊，本地 Mac 仍可能較合適；但對需要隔離建置、SSH 管理及可回退環境的團隊，遠端 Mac 通常比直接改動唯一的生產主機更容易控制風險。