Branching 分支開發：每個 PR 一套隔離的 Supabase 環境 | Supabase 完整教學

上一篇我們把每一次 schema 變更都變成帶時間戳、納入 git 的遷移檔，打通了「本機 → 生產」的單向流水線。但當團隊多人協作、每個 Pull Request 都想要一份「獨立、隔離、帶完整 schema 與 seed」的預覽環境時，光靠 db push 還不夠。本篇主角 Supabase Branching（分支開發） 就是答案：它讓每個 Git 分支對應一套隔離的 preview branch（預覽分支）——有自己的資料庫、Auth、Storage——並透過 GitHub 整合，在你開 PR 時自動建立預覽環境、自動套用遷移與 seed，等你合併回 production 時再把遷移正式套上線。我們會走一遍啟用流程、PR 自動建環境的機制、合併上線的路徑，也會說清楚計費成本、資料不是 production 副本、secrets 要另外帶這幾個新手最容易踩的坑。

前言

先一句話定義本篇主角：Supabase Branching（分支開發）就是「讓每一個 Git 分支，都對應一套完全隔離、可獨立運行的 Supabase 環境」的機制。 當你在 GitHub 上為某個功能開一個分支、發一個 Pull Request，Supabase 可以自動為這個 PR 生出一支 preview branch（預覽分支）——它有自己的資料庫、自己的 Auth 設定、自己的 Storage、自己的 API URL 與金鑰，和你的正式 production 環境徹底分家。reviewer 打開這個 PR 的預覽連結，看到的就是「這個功能在一套乾淨、獨立環境裡跑起來的樣子」，完全不會動到、也不會污染正式資料庫。

用一個類比理解為什麼要這麼做。preview branch 對資料庫環境，就像 GitHub 上的 feature branch 對程式碼。 你不會在 main 上直接改 code——你開一個分支、在上面實驗、發 PR 讓人 review、確認沒問題才 merge 回 main。但長久以來，「程式碼」有分支、「資料庫環境」卻沒有：大家共用一套 staging、甚至有人直接連 production 測試，一個人的 schema 實驗常常擋到另一個人。Branching 就是把「程式碼那套 branch 的隔離紀律」搬到整個後端環境上：每一個 Git 分支 = 一套隔離的 Supabase 環境 = 一份互不干擾、可獨立驗證的預覽。

而這一切能自動運轉的關鍵，是它和上一篇《Migrations 資料庫遷移》的無縫接軌。preview branch 不是憑空生出一個資料庫，而是拿你 repo 裡 supabase/migrations/ 的遷移檔，在這支分支上重新播放一遍得到 schema，再跑 seed 填入測試資料。所以上一篇打下的「遷移即真相來源」的地基，正是 Branching 能自動化的前提——遷移工作流做得越紮實，Branching 用起來越順。

本篇你會學到：

• Branching 的核心模型：Git 分支 ↔ 隔離的 preview branch 環境，遷移如何自動套到 branch 上
• GitHub 整合與 PR 自動建環境：如何啟用、PR 推送時 Supabase 自動執行哪些步驟
• 兩種分支類型與合併上線：preview branch（臨時）vs. persistent branch（持久／staging），以及合併回 production 的路徑
• 成本與陷阱：preview branch 的計費、branch 資料非 production 副本、secrets 沒帶過去等常見坑

本篇聚焦「Branching 分支開發」這一件事。CLI 安裝、本機環境、遷移工作流已在前兩篇講透，這裡假設你已經能 supabase start 跑起本機堆疊，也能用 supabase migration new／db diff 產生遷移。Branching 是一項針對特定方案提供的進階功能，且其計費方式、啟用選項、自動化步驟細節都可能隨版本調整，正式決策前一律以官方文件與定價頁為準。

核心概念

在動手啟用之前，先建立三張心智圖：一是「Git 分支如何對應到隔離的 Supabase 環境」，二是「遷移如何自動套到 branch 上」，三是「preview branch 與 persistent branch 的差別」。

一、Git 分支 ↔ 隔離的 Supabase 環境

Branching 的核心，是把「一個 Git 分支」和「一套 Supabase 環境」綁在一起。下面這張圖是整個機制的骨架：

GitHub Repo                          Supabase 專案
─────────────────────────────────────────────────────────
main 分支          ─────────────►    Production（正式環境）
  │                                    └ 正式資料庫 / Auth / Storage
  │
  ├─ feat/add-comments  (開 PR) ──►   Preview Branch A（隔離）
  │                                    └ 專屬資料庫 / Auth / Storage
  │                                    └ 專屬 API URL + anon key
  │
  └─ feat/new-checkout  (開 PR) ──►   Preview Branch B（隔離）
                                       └ 又一套獨立環境
                                       └ 又一組專屬 URL + key

幾個關鍵性質：

• 每支 preview branch 是「完整的一套 Supabase」：不是只複製一個資料庫，而是連 Auth 設定、Storage、Edge Functions 都有自己的一份，彼此隔離。
• 每支 preview branch 有專屬的連線資訊：獨立的 API URL 與 anon／service key。這就是為什麼「前端要連到某支 preview」時，你得指向它專屬的 URL 與金鑰，而不是正式環境那組。
• production 對應 main（或你設定的正式分支）：正式環境只有一個，其他 feature 分支各自對應臨時的 preview。

二、遷移如何自動套到 branch 上

第二張心智圖，是「一支 preview branch 從無到有」的過程——而它的核心，正是上一篇的遷移機制。當 GitHub 整合偵測到一個 PR、要為它建立 preview branch 時，Supabase 大致會做這幾件事（步驟名稱與細節以官方為準）：

①  Clone      取得 GitHub repo 上這個分支的內容
②  Pull       從正式專案取得既有的遷移基準
③  Health     確認這套新環境的各項服務正常啟動
④  Configure  套用 repo 裡 supabase/config.toml 的設定
⑤  Migrate    依序套用 supabase/migrations/ 的遷移（+ 相關 secrets）
⑥  Seed       執行 seed 檔，填入初始測試資料
⑦  Deploy     部署 Edge Functions 等，更新對應設定

這張圖最重要的一列是 ⑤ Migrate：你在這個分支裡新增的遷移檔，會被自動、依序套用到這支 preview branch 上。 換句話說，你不需要手動對 preview 環境 db push——只要遷移檔進了這個分支的 repo，Supabase 建 branch 時就會把它重播一遍。這也是為什麼上一篇的紀律那麼重要：遷移檔就是這套自動化的「輸入」，遷移寫得乾淨、能從零重播，preview branch 才建得起來。 任一步驟失敗（例如某支遷移在乾淨環境重播時報錯），後續相依步驟通常會被跳過，而你會在 PR 上看到失敗回報。

三、preview branch vs. persistent branch

第三張心智圖，是分辨兩種分支——它們的生命週期與用途完全不同：

一句話記法：preview branch 是「用完即丟的臨時預覽」，persistent branch 是「長期常駐的 staging」。 大多數 feature 開發用 preview branch（跟著 PR 生、跟著 PR 滅、閒置會暫停，成本可控）；而如果你需要一個「長期穩定、不會被自動收掉」的整合環境，就用 persistent branch。這個區分後面談成本時還會再提——因為「持久」意味著它不會自動暫停，計費行為也不同。

四、關鍵術語速查

實作範例

Branching 的「操作」大多發生在 Supabase Dashboard 與 GitHub 上，而不是像前幾篇那樣一連串本機指令。下面走一遍完整流程：啟用 GitHub 整合 → 開 PR 自動建 preview → 在 branch 上迭代遷移 → 合併回 production → 用 CLI 查看／管理分支。

一、啟用 Branching（連結 GitHub）

Branching 的入口在 Dashboard。大致步驟如下（實際選單位置與流程以官方為準）：

1. 進入 Supabase Dashboard → 選擇你的正式專案
2. 前往 Settings → Integrations → GitHub
3. 授權並連結你要整合的 GitHub 儲存庫（repo）
4. 指定「正式分支」（通常是 main），並在 GitHub 端保護 main 分支
5. 啟用 Branching 功能

連結完成後，這個 repo 與你的 Supabase 專案就掛上鉤了：往後只要有非正式分支的 PR 推送，Supabase 就會自動介入。要注意的是，Branching 是針對特定方案提供的進階功能，啟用前請先確認你的方案支援、並看清楚計費方式（下一節詳談）。

二、開一個 PR，自動長出 preview branch

啟用後，你的日常開發流程幾乎不變——差別是「每個 PR 現在會自動附帶一套環境」。用上一篇熟悉的 feature 分支流程示範：

# 從正式分支開一支功能分支
git checkout -b feat/add-comments

# 照前兩篇的做法，在本機做 schema 變更並產生遷移
supabase migration new add_comments_table
# ...編輯 supabase/migrations/2026...._add_comments_table.sql...

# 本機先驗證遷移能乾淨重播（上一篇的鐵律）
supabase db reset

# 提交遷移並推上 GitHub，開 PR
git add supabase/migrations/
git commit -m "feat: add comments table migration"
git push origin feat/add-comments

當你在 GitHub 上針對這支分支開 PR，Supabase 會自動偵測、為這個 PR 建立一支專屬的 preview branch：clone 你的分支、套用 supabase/config.toml、依序重播 supabase/migrations/（包含你剛才那支 add_comments_table）、跑 seed、部署 Edge Functions。完成後，這支 preview branch 就擁有一套「帶著你新遷移」的完整環境，以及專屬的 API URL 與金鑰。

這裡最值得體會的一點是：你「建立 comments 表」這件事，不需要對任何遠端環境手動 db push。 只要遷移檔進了這個 PR 的分支，preview branch 建起來時就自動把它套上了——這就是遷移自動化的威力。

三、把前端接到 preview 環境（以 Vercel Preview 為例）

每支 preview branch 有自己的 URL 與金鑰，所以「前端要連到哪」變成關鍵。實務上常見的做法，是讓部署平台的「預覽部署」自動指向 preview branch 的連線資訊。以 Vercel 為例，在專案的環境變數中，區分 Production 與 Preview 兩種範圍：

# Production（對應 main / 正式 Supabase 專案）
NEXT_PUBLIC_SUPABASE_URL=https://your-prod-ref.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOi...（正式環境 anon key）

# Preview（對應 PR 的 preview branch，指向該分支專屬 URL / key）
NEXT_PUBLIC_SUPABASE_URL=https://your-preview-ref.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOi...（preview 環境 anon key）

如此一來，reviewer 打開 PR 的 Vercel Preview Deployment 連結，前端就會連到那支隔離的 preview branch，看到「這個功能搭配它專屬後端環境跑起來的完整樣子」；而 Production 部署仍舊乾淨地指向正式專案。實際上要如何把 preview branch 的動態 URL／金鑰餵給部署平台，各家整合方式不同，請以官方文件與該平台文件為準。

四、合併回 production：遷移正式上線

reviewer 看過 preview、確認功能沒問題後，就可以 merge 這個 PR。當 PR 合併回正式分支（如 main），這條路徑會把該分支帶進來的遷移套用到 production，讓 schema 變更正式生效；同時，那支臨時的 preview branch 因為 PR 已關閉，會被自動刪除、釋放資源。

feat/add-comments 的 PR
        │  (reviewer 在 preview branch 上驗證 OK)
        ▼
   merge 進 main
        │
        ├─►  遷移套用到 production（schema 正式上線）
        │
        └─►  對應的 preview branch 自動刪除、停止計費

這條路徑，等於把上一篇手動的「db push 到生產」這一步，接進了 GitHub 的 merge 動作裡：遷移的部署時機，從「人記得去 push」變成「PR 合併時自動發生」。 這正是 Branching 把遷移工作流「無縫接進協作與 CI/CD」的意義所在——它讓「本機 → 預覽 → 生產」的每一段都自動化、且有 PR 作為審核關卡。

五、用 CLI 查看與管理分支

雖然多數操作在 Dashboard 與 GitHub 上完成，CLI 仍提供了查看與管理分支的指令，方便你在終端機掌握狀態（指令與旗標以官方為準）：

supabase branches list                    # 列出目前所有分支
supabase branches switch <branch-name>    # 切換作用中的分支
supabase branches delete feat/old-thing   # 手動刪除某支分支

若你要用 config.toml 為不同遠端環境（例如 staging）覆寫設定，可以用 remotes 區塊指定不同的專案與參數：

# supabase/config.toml

# staging 使用不同的遠端專案
[remotes.staging]
project_id = "your-staging-project-id"

# 覆寫 staging 環境的 Auth 設定（例如正式網域的重導向）
[remotes.staging.auth]
site_url = "https://staging.yourapp.com"
additional_redirect_urls = [
  "https://staging.yourapp.com",
  "https://staging.yourapp.com/auth/callback"
]

這讓你能在同一份 repo 裡，為不同環境維護對應的設定——例如 staging 用它自己的網域與 Auth 重導向，而不必手動改來改去。

常見錯誤與最佳實踐

坑一：以為 preview branch 裡有 production 的資料。 最常見的誤解，是把 preview branch 想成「production 的完整副本」。實際上 preview branch 預設只複製 schema（靠重播遷移得到），不含 production 的實際資料列，它是從一個空資料庫加上你的 seed 開始的。這其實是刻意的安全設計——避免把正式使用者的個資帶進臨時預覽環境。正確做法：不要期待去「複製 production 資料」，而是把 seed 準備得夠完整，讓每支 preview branch 一建好就有足夠的測試資料可以 demo、可以點測。若真的需要接近正式資料的測試場，另外用 persistent branch 當 staging 環境，而非硬把 production 資料塞進臨時 preview。

坑二：忘了 Branching 是要花錢的，放一堆殭屍分支長期掛著。 每一支活躍的 preview branch 本質上是「一套額外運行的 Supabase 實例」，會產生對應費用，通常以運行時間計費。若團隊同時開十個 PR、每個都掛著 preview branch，就是十套環境同時在計費。正確做法：善用 Supabase 的省成本機制——preview branch 在 PR 合併或關閉時會自動刪除、閒置一段時間會自動暫停；養成「不需要的 PR 及時合併或關閉」的習慣，別讓殭屍分支長期存在；長期 staging 用單一 persistent branch 管理，而不是靠一堆 preview branch。導入前，務必到官方定價頁確認方案是否包含 Branching、以及每支 branch 的實際計費方式（以官方為準）。

坑三：secrets 與環境變數沒帶到 preview branch，導致「本機好好的、preview 卻壞了」。 preview branch 會自動套遷移，但它不會憑空擁有你本機 .env 裡的那些敏感值——像 Vault secrets、Edge Function 需要的 API 金鑰、第三方服務的環境變數，通常得事先在 Supabase 專案層（或透過 config.toml 相關設定）配置好，preview branch 才會帶到。第一次用 Branching 遇到「遷移都套了、功能卻報錯」，十之八九就是某個 secret 沒帶過去。正確做法：導入 Branching 時，把「這個環境需要哪些 secrets／環境變數」列成清單，確認它們在專案層有設定、且會被 branch 繼承；並記得 config.toml 裡以 env() 引用的敏感值，其來源在 preview 環境是否可得。

坑四：在 preview branch 上直接手動改 schema，繞過遷移。 Branching 的整套自動化，建立在「遷移檔是唯一真相來源」之上。如果你圖方便，直接在某支 preview branch 的 Dashboard 上點按改了 schema，卻沒把變更寫成遷移檔進 repo——這支 branch 一旦重建（或 merge 回去）就會遺失那些變更，本質上是上一篇 schema drift 的翻版。正確做法：所有 schema 變更一律走遷移檔——在本機用 migration new／db diff 產生遷移、db reset 驗證、commit 進 PR 分支，讓 preview branch 透過重播遷移得到 schema。preview branch 是拿來「驗證」的，不是拿來「手改」的。

坑五：破壞性遷移直接靠 merge 打上 production。 Branching 讓「merge 就自動套遷移到 production」變得很順手，但這也意味著破壞性變更（drop column、drop table、改型別）會隨著 merge 自動生效在正式環境。正確做法：破壞性變更前，先在 preview 環境（甚至 persistent staging）完整演練；遷移盡量拆成「向後相容的多步」（先加新欄位、程式雙寫過渡、確認無虞後才在後續遷移刪舊）；沿用上一篇的紀律，重大變更前先以 --dry-run 之類的方式看清楚將執行的 SQL 再上線。

最佳實踐總結：

• preview 不是 production 副本：靠重播遷移得到 schema，資料來自 seed；把 seed 準備完整
• 成本要盯著：每支活躍 branch 都在計費，及時收掉殭屍分支、善用自動暫停與刪除
• secrets 要另外備妥：在專案層設定好敏感值與環境變數，別讓 preview 因缺 secret 而壞
• 一切走遷移：不要手改 preview schema，所有變更成遷移檔、進 PR、由 branch 重播
• 破壞性變更謹慎：先在 preview／staging 演練，拆成向後相容的多步再上生產
• 細節以官方為準：計費方式、啟用選項、自動化步驟都可能隨版本調整

小結

這是 Supabase 系列教學的第 041 篇，緊接上一篇《Migrations 資料庫遷移》。上一篇我們把每一次 schema 變更都變成帶時間戳、納入 git、能一鍵重播的遷移檔，打通了「本機 → 生產」的單向流水線；但留下一個問題：多人協作時，每個 PR 都想要一份「獨立、隔離、帶完整 schema 與 seed」的預覽環境，光靠 db push 不夠。這一篇的 Branching，就把那條遷移工作流無縫接進了 GitHub 的協作與 CI/CD。

核心觀念濃縮成一句話：Supabase Branching 讓「每個 Git 分支對應一套隔離的 Supabase 環境」；透過 GitHub 整合，開 PR 時自動建立 preview branch（依序重播 supabase/migrations/ 的遷移、跑 seed、給一套專屬 URL 與金鑰），reviewer 在這套隔離環境驗證後 merge，遷移就自動套用到 production 正式上線，臨時的 preview branch 也自動刪除——它把上一篇手動的『push 到生產』接進了 merge 動作，讓『本機 → 預覽 → 生產』每一段都自動化、可審核。

• 核心模型：Git 分支 ↔ 隔離 Supabase 環境；preview branch（臨時、隨 PR 生滅、閒置自動暫停）vs. persistent branch（長期常駐、當 staging）
• 自動化機制：GitHub 整合在 PR 上自動建 branch，依序重播遷移、跑 seed、部署 functions；merge 回 production 時遷移正式生效
• 前端接法：每支 preview branch 有專屬 URL／金鑰，搭配部署平台（如 Vercel）的 Preview 部署自動指向
• 成本與坑：每支活躍 branch 都計費、branch 資料非 production 副本、secrets 要另外備妥、一切走遷移

Branching 讓多人協作的每個 PR 都有了隔離、可審核的預覽環境。但你可能已經注意到：在 preview 環境驗證遷移、生成正確的 TypeScript 型別、在 merge 前跑自動化檢查——這些「重複、機械、該自動跑」的事，其實可以完全交給機器。下一篇《型別生成與 CI/CD》，我們會把 supabase gen types 產生的型別定義納入版控與流水線，並用 GitHub Actions 串起「PR 驗證遷移 → 生成型別 → 部署 Staging → 部署 Production」的完整自動化，讓整條後端工作流真正跑成一台不用人顧的機器。