Supabase 在 2026 年 11 月 2 日發布 CLI v3.0.0，11 月 4 日再以 Breaking Change 公告整理影響。npm、Scoop、Linux packages 與未固定版本的 supabase/setup-cli 已會安裝 v3，Homebrew 的一般安裝也從 11 月 3 日起指向 v3。這代表即使團隊沒有主動改部署腳本，只要 CI 每次抓 latest，工作流程就可能已經換版。

這次改動不是 Supabase 代管服務故障，也不影響自架 Supabase runtime；改變的是 CLI 如何選擇本機或遠端目標、如何確認遠端寫入，以及設定值的優先順序。最值得注意的風險不是「指令語法變了」而已，而是同一行 supabase db push 在 v3 預設改為本機目標。若 CI 沒有啟動本機 stack，它會失敗；若前一步剛好啟動了本機 stack，指令甚至可能成功，但正式專案完全沒有更新。

哪些流程需要優先檢查

先搜尋 repository、部署平台設定與維運文件裡所有 supabase 指令。高風險範圍包括資料庫 migration、型別產生、schema dump、Storage 檔案操作、Edge Functions 部署、Secrets 更新與 config push。db push、db pull、db dump、migration list、gen types 與 Storage 指令現在沒有 target flag 時都走本機；要存取代管專案必須明確加入 --remote。

第二類風險是無人值守寫入。v3 對代管專案的變更預設先詢問，且預設答案是 No；CI、JSON 輸出或 AI agent 等不能互動的執行環境，若沒有 --yes，會以 HostedMutationConsentRequiredError 結束。把 y pipe 進 stdin 不再算確認。這個設計降低誤改正式環境的可能性，但舊 pipeline 會直接中斷，不能只把失敗當成暫時性網路問題重試。

第三類是舊設定。較早版本 supabase init 產生的 [inbucket] 要先改名為 [local_smtp]；否則 v3 甚至無法載入設定。若專案使用具名的 [remotes.NAME] 區塊，也要盤點 CI 中的 SUPABASE_* 變數，因為 v3 的解析順序改成 command flag、shell environment、project env file、config，環境變數可能覆蓋原本預期的 remote block。

先固定版本，再安排可回復的過渡

不要讓每次部署邊跑邊決定 major version。若目前尚未完成盤點，可暫時固定 [email protected]；GitHub Actions 則使用 supabase/setup-cli@v3 並設定 version: v2.stable。官方說明指出 v2 仍會收到安全與破損行為修正，但不再加入新功能，所以固定 v2 是過渡手段，不是永久逃避遷移。

在 v2.122.0 以上先執行原有的本機與 CI 流程，處理它對移除指令、舊 flag 與目標改變的警告。接著把遠端意圖寫進命令列：例如正式 migration 改為 supabase db push --remote --yes，讀取遠端 migration history 改為 supabase migration list --remote，部署 Function 則加入 --yes。如果要指定 ref、branch 或資料庫 URL，使用 --remote=VALUE，不要寫成中間有空格的形式。

每個 job 都應明確回答兩個問題：目標是哪裡，以及這一步是否被授權寫入。讀取流程不應為了省事全面加入 --yes；寫入流程則應放在受保護環境、人工核准或限制分支之後。正式與 staging 使用不同 project ref、access token 和 environment，避免「有 --remote」卻連到錯誤專案。

驗收不能只看 exit code

先在測試分支建立 v2 與 v3 兩條 pipeline，輸入相同 migration。v3 執行前記錄 CLI 顯示的 Target:，執行後同時查核遠端 migration history、schema 版本與本機 stack，確認變更只出現在預期位置。型別產生也要比較內容，因為未加 --remote 時可能從本機資料庫產生一份語法正確但版本落後的型別檔。

對每種遠端寫入至少測三個情境：缺少 --yes 時必須安全失敗、加入 --yes 後只改 staging、使用錯誤或不存在的 remote 時不能 fallback 到其他目標。若腳本解析 JSON error、固定比對錯誤字串或依賴輸出欄位，也要納入測試；v3 新增 target object 並調整部分錯誤名稱，單純 grep 舊文字可能誤判成功與失敗。

升級前執行 supabase config diff，特別檢查 Auth SMS confirmation 與由環境變數覆蓋的設定。正式 rollout 採先 staging、再非尖峰時段 production；保留 v2 lockfile 或明確的版本 pin，才能在 CLI 行為不符合預期時回復，而不是臨時重新安裝一個不確定的版本。

怎麼選遷移時機

部署流程少、已把 CLI 鎖在專案 devDependency 的團隊，可以直接建立 v3 migration PR，逐行標示 local、remote、read 與 write。流程分散在多個 repository 或維運人員電腦的團隊，應先固定 v2，建立指令清冊與 owner，再分批升級。使用自架 Supabase 的團隊雖不受代管 CLI rollout 直接影響，若日常仍用 CLI 管理本機開發環境，也要確認被移除的設定與指令。

CLI v3 的方向是把「修改正式環境」從隱含預設改成明確選擇。完成遷移後，部署腳本會多幾個 flag，卻也更容易在 code review 看出目標與寫入意圖。真正的完成條件不是 pipeline 重新變綠，而是能證明每一步改了哪一個專案、失敗時沒有改動，以及 rollback 使用哪個固定版本。