Supabase 在 2026 年 11 月 6 日公布 Flutter 與 Dart client v3 的 breaking-change 說明。目前可測的是 3.0.0-dev prerelease,穩定版排定 11 月 11 日推出;因此現在不能寫成 v3 已正式發布。使用 ^2.x constraint 的專案也不會自動升到 v3,pub 不會在未明確指定時選 prerelease,既有 App 今天不會無故被換版。

這次 major upgrade 的核心是端到端型別。CLI 可從資料庫 schema 產生每張表的 row、insert 與 update 定義,新 table() API 讓查詢結果不再只是以字串為 key、動態值為內容的 Map,filter、order、write、embedded select、stream 與 RPC 都能帶著欄位型別。這能讓欄位改名更早在 build 階段暴露,但不代表升級只要修完 compile error 就完成。

編譯器抓不到的變更才是發布風險

官方特別提醒兩類 silent behavior change。第一是 order() 的預設排序方向;依賴舊預設但沒有明寫 ascending 的畫面,升級後可能成功編譯、資料也能回傳,順序卻與原本不同。訂單、訊息、活動紀錄與庫存批次若顯示順序顛倒,往往直到使用者操作才被發現。

第二是 v2 與 v3 的 Realtime broadcast payload 不相容。若同一 channel 同時有舊版與新版行動 App,兩邊可能讀不到彼此預期的位置。行動 App 不像網站能同時刷新所有使用者,App Store rollout 期間必然存在多版本並存,因此不能假設「後端沒有改 schema」就可安全分批更新。

另外,anonKey 參數改名為 publishableKey,但既有 anon key 仍是有效的值;這是 API 命名遷移,不是金鑰立即失效。直接依賴 gotrue、realtime_client、storage_client 與 functions_client 的專案也要改用重新命名的 packages。把每一個 rename 都當成重新產生 credential,反而會製造不必要的停機與環境差異。

先決定一次升級,還是逐表採用型別

from() 在 v3 仍可使用,且能與 table() 共存,所以大型專案不必在同一個 PR 改完所有 query。較穩健的方式是先完成 SDK major upgrade 與行為相容,再從風險高、測試完整的 table 開始導入型別;每次產生 schema types 都進版控,讓 code review 看得到欄位、nullable 與 foreign key 的變化。

小型 App 若查詢不多、沒有 Realtime broadcast、測試覆蓋完整,可以在獨立分支一次改完。大型或白牌 App 則建議把工作拆成四層:package 與初始化、Auth 與 token、資料查詢與 RPC、Realtime 與 Storage。每層建立 owner 與驗收案例,避免大量 compiler fix 淹沒真正的行為改變。

使用型別產生時,官方要求 Supabase CLI 2.122.0 或更新版本。CLI 本身在本週也有 v3 重大更新,專案應把「Flutter client v3」與「Supabase CLI v3」視為兩個可獨立控制的升級,不要同一天同時更換 client、產生器與部署命令。先固定 CLI 版本,記錄產生指令與目標 project,再比較生成檔 diff,才能知道差異來自 schema 還是工具版本。

可執行的遷移順序

第一步在 v2 分支搜尋所有 order(),對依賴 descending 的查詢明確加入 ascending: false,並用固定資料集建立排序測試。再列出所有 Realtime channel、broadcast event、sender 與 receiver 版本,標出是否跨 Web、iOS、Android、背景 worker 或多個 App。

第二步建立 v3 migration branch,鎖定明確 prerelease 版本,不在正式環境使用浮動的 dev constraint。依官方 migration guide 更換 packages、初始化參數、錯誤型別與 client API。先讓現有測試在 from() 上恢復,再選一張表導入 supabase_typegen 與 table();這樣出錯時能區分 major upgrade 與 typed query 改寫。

第三步補上 compiler 不會替你驗證的測試:預設排序、null handling、timestamp、URL、Auth state、exception mapping、token refresh、Storage error,以及 v2/v3 broadcast 交叉矩陣。測試不能只有兩個 v3 client 互傳,還要用正式仍可能存在的 v2 版本與 v3 測試版互相發送。

第四步安排 rollout。若 App 的即時功能必須跨版本互通,可先讓後端或訊息層接受兩種 payload,等最低支援版本提高後再移除相容層;若無法建立雙讀,官方建議共享 broadcast channel 的 App 同時發布。這裡的「同時」仍要考慮審核與使用者更新延遲,必要時先暫停受影響功能或改用版本化 channel,而不是假設商店發布等於全部安裝。

升級時機如何選

現在適合做 inventory、建立測試與試跑 dev prerelease,不適合在沒有 rollback 的情況下搶先升正式環境。Supabase 表示 v2 在 v3 stable 後仍有六個月的安全與 critical fixes,因此沒有新 v3 功能需求的團隊可以等穩定版、已知問題與相依套件陸續收斂,再排入正常 release train。

需要 typed API、正在大改 schema,或常因動態 Map 在執行期出錯的專案,則可提早建立 migration branch。但正式切換前要重新核對 11 月 11 日實際發布內容,因為 GitHub migration guide 目前仍註明是跟著 main 更新的 running list,不應把 11 月 7 日看到的文件當成永不變動的最終規格。

完成標準不是「編譯通過」,而是排序與 Realtime 行為已驗證、CLI 與 SDK 版本分開固定、generated types 可重現、舊 App 與新 App 的共存策略可執行,且可以回到最後一個 v2 release。型別化會把很多錯誤提前,但 major upgrade 的風險仍藏在型別系統看不到的跨版本行為。