Communitygithub.com

Supabase 完整開發指南

處理任何涉及 Supabase 的任務時使用。涵蓋資料庫、身分驗證、邊緣函式、即時功能、儲存空間、向量搜尋、排程器、佇列、用戶端函式庫、SSR 整合、CLI、MCP 伺服器、結構變更、安全性稽核及疑難排解。

Supabase 完整開發指南 是什麼?

這份技能提供了一套完整的 Supabase 開發參考指南,它是所有 Supabase 相關任務的核心知識庫。技能的核心在於強調實踐與安全性,它不僅列出了六大核心原則,還提供了詳細的安全檢查清單,涵蓋了 Auth、RLS、View、Storage 和供應鏈安全等極易被忽略的陷阱,並明確指出如 `user_metadata` 不應用於授權、View 預設繞過 RLS 等關鍵注意事項。 對於開發流程,技能詳細說明了如何正確使用 Supabase CLI 和 MCP 伺服器,包括版本檢查、常見陷阱的解決方案以及連線除錯步驟。在結構變更方面,它區分了「宣告式結構」與「指令式遷移」兩種工作流程,並強烈建議在迭代時使用 `execute_sql` 或 `supabase db query` 直接操作資料庫,最後再產生乾淨的遷移檔案,以避免歷史記錄混亂。 此外,技能還提供了嚴謹的資料查閱方法,優先使用 MCP 的 `search_docs` 工具或直接擷取文件頁面的 Markdown。當遇到錯誤時,技能要求必須查閱官方的「監控與除錯」文件,而非依賴記憶來進行診斷。整體而言,這份技能旨在讓開發者或 AI 代理能以高效、安全且可驗證的方式使用整個 Supabase 生態系,並從錯誤中有效恢復。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Futurists2023/tiktok/tree/HEAD/.agents/skills/supabase

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Supabase

核心原則

1. Supabase 變更頻繁——請在實作前查閱變更記錄與最新文件。 請勿依賴訓練資料來使用 Supabase 功能。函式簽章、config.toml 設定與 API 慣例會因版本而異。

首先,獲取 https://supabase.com/changelog.md(一個輕量級的摘要索引——非大量下載),掃描與你的任務相關的 breaking-change 標籤,並依照連結的頁面處理。接著,使用下方的文件存取方法查閱相關主題。

2. 驗證你的工作。 實作任何修正後,請執行測試查詢來確認變更有效。未經驗證的修正是不完整的。

3. 從錯誤中恢復,不要無限循環。 如果某個方法在 2-3 次嘗試後仍失敗,請停止並重新考慮。嘗試不同方法、查閱文件、更仔細地檢查錯誤,並在可用時檢閱相關日誌。Supabase 的問題並非總是能透過重複相同指令解決,答案也不總是在日誌中,但在繼續之前檢查日誌通常是值得的。

4. 將資料表暴露給 Data API: 根據使用者的 Data API 設定,新建立的資料表可能不會自動暴露給 Data (REST) API。如果是這種情況,則需要明確授予 anon 和 authenticated 角色存取權限。

請注意,這與 RLS 不同,RLS 控制的是資料表可存取後哪些行可見,而不是資料表本身是否可存取。

當使用者回報透過 SQL 建立的資料表意外無法存取時,請檢查他們的 Data API 設定,以及是否已透過明確的 GRANT SQL 授予角色存取權限。在授予公開 (anon/authenticated) 存取權限時,務必同時啟用 RLS。請參閱 將資料表暴露給 Data API 了解完整的設定工作流程。

5. 暴露結構中的 RLS。 在暴露結構中的每個資料表上啟用 RLS,預設包含 public。這在 Supabase 中至關重要,因為暴露結構中的資料表在 anon/authenticated 角色擁有存取權限時(請參閱將資料表暴露給 Data API),可透過 Data API 存取。對於私有結構,建議將 RLS 作為深度防禦措施。啟用 RLS 後,請建立符合實際存取模型的原則,而不是讓每個資料表都預設使用相同的 auth.uid() 模式。

6. 安全檢查清單。 在處理任何涉及 auth、RLS、檢視表、儲存空間或使用者資料的 Supabase 任務時,請執行此檢查清單。這些是 Supabase 特有的安全陷阱,會無聲地創造漏洞:

  • Auth 與 session 安全性

    • 切勿在基於 JWT 的授權決策中使用 user_metadata 聲明。 在 Supabase 中,raw_user_meta_data 是使用者可編輯的,且可能出現在 auth.jwt() 中,因此對 RLS 原則或任何其他授權邏輯來說是不安全的。請改為將授權資料儲存在 raw_app_meta_data / app_metadata 中。
    • 刪除使用者不會使現有的存取權杖失效。 請先登出或撤銷 session,對於敏感應用程式請保持 JWT 短期有效,對於嚴格保證,請在敏感操作上針對 auth.sessions 驗證 session_id。
    • 如果你使用 app_metadata 或 auth.jwt() 進行授權,請記住 JWT 聲明在使用者的權杖刷新之前並非總是最新的。
  • API 金鑰與客戶端暴露

    • 切勿在公開客戶端中暴露 service_role 或密鑰。 前端程式碼建議使用可發布金鑰。舊版的 anon 金鑰僅用於相容性。在 Next.js 中,任何 NEXT_PUBLIC_ 環境變數都會被發送到瀏覽器。
    • 對 Management API、CLI 和 MCP 伺服器使用範圍限定個人存取權杖。 經典的個人存取權杖會攜帶使用者在每個組織和專案上的完整帳戶存取權限。對於腳本、CI 和代理,請讓使用者建立一個範圍限定權杖,僅限於任務所需的組織、專案和權限。個人存取權杖指南 列出了每個 Management API 端點和 MCP 工具所需的權限。請在那裡查閱權限,而不是猜測。
  • RLS、檢視表和特權資料庫程式碼

    • 檢視表預設繞過 RLS。 在 Postgres 15 及以上版本中,使用 CREATE VIEW ... WITH (security_invoker = true)。在較舊的 Postgres 版本中,透過撤銷 anon 和 authenticated 角色的存取權限,或將檢視表放置在未暴露的結構中來保護它們。
    • UPDATE 需要 SELECT 原則。 在 Postgres RLS 中,UPDATE 需要先 SELECT 該行。如果沒有 SELECT 原則,更新會默默地回傳 0 行——沒有錯誤,只是沒有變更。
    • auth.role() 已棄用——請改用 TO 子句。 Supabase 已棄用 auth.role(),改為直接在原則上使用 TO authenticated 或 TO anon 來指定目標角色。除了棄用之外,當啟用匿名登入時,auth.role() = 'authenticated' 會無聲地失效,因為匿名使用者帶有 authenticated 的 Postgres 角色,無論使用者是否真正登入都會通過檢查。
      -- 已棄用(請勿使用)
      create policy "example" on table_name for select
      using ( auth.role() = 'authenticated' );
      
    • 單獨使用 TO authenticated 是身份驗證而非授權(BOLA / IDOR)。 使用 TO authenticated 僅檢查角色——它不限制使用者可以存取哪些行。正確的模式是將 TO authenticated 與 USING 中的所有權謂詞結合:
      create policy "example" on table_name for select
      to authenticated
      using ( (select auth.uid()) = user_id );
      
    • UPDATE 原則需要 USING 和 WITH CHECK。 沒有 WITH CHECK,使用者可以將行的 user_id 重新指派給另一個使用者:
      create policy "example" on table_name for update
      to authenticated
      using ( (select auth.uid()) = user_id )
      with check ( (select auth.uid()) = user_id );
      
    • SECURITY DEFINER 函數會繞過 RLS。 SECURITY DEFINER 函數以其建立者的權限執行——通常是具有 bypassrls 的角色(例如 postgres)。切勿為了解決權限錯誤而添加 SECURITY DEFINER;它會在未解決根本原因的情況下默默地移除存取控制。請優先使用 SECURITY INVOKER。
    • public 中的 SECURITY DEFINER 函數可被所有角色呼叫。 Postgres 預設為每個新函數授予 PUBLIC EXECUTE 權限,因此 public 中的任何 SECURITY DEFINER 函數都是一個公開的 API 端點,可由 anon 和 authenticated(從 PUBLIC 繼承)存取,無需任何額外授權。當確實需要 SECURITY DEFINER 時(例如繞過內部查詢表的 RLS),請將函數保留在未暴露的結構中,始終在函數體內包含 auth.uid() 檢查,並在進行變更後執行 supabase db advisors。
  • 儲存空間存取控制

    • 儲存空間的 upsert 需要 INSERT + SELECT + UPDATE。 僅授予 INSERT 允許新上傳,但檔案替換(upsert)會無聲地失敗。你需要全部三個權限。
  • 依賴項與供應鏈安全性

    • 安裝 Supabase 套件(supabase-js、@supabase/ssr、supabase-py 等)時,請務必鎖定套件版本並提交鎖定檔案。 請參閱 npm 安全指南 了解完整檢查清單。

對於上述未涵蓋的任何安全問題,請查閱 Supabase 產品安全索引:https://supabase.com/docs/guides/security/product-security.md

Supabase CLI

始終透過 --help 來探索指令——切勿猜測。CLI 結構會因版本而異。

supabase --help                    # 所有頂層指令
supabase <group> --help            # 子指令(例如 supabase db --help)
supabase <group> <command> --help  # 特定指令的旗標

Supabase CLI 已知陷阱:

  • supabase db query 需要 CLI v2.79.0+ → 改為使用 MCP execute_sql 或 psql 作為備用方案
  • supabase db advisors 需要 CLI v2.81.3+ → 改為使用 MCP get_advisors 作為備用方案
  • supabase login 的瀏覽器流程會建立一個帶有完整帳戶存取權限的經典權杖。在 CI 環境中,請改為將 SUPABASE_ACCESS_TOKEN 設為一個範圍限定個人存取權杖。它優先於任何已儲存的登入資訊。使用資料庫密碼連接的指令(--password 或 SUPABASE_DB_PASSWORD,例如 supabase db push)不受權杖權限的限制。
  • 在指令式遷移專案中,首先使用 supabase migration new <name> 建立新的手動編寫遷移檔案。切勿憑空發明遷移檔名或依賴記憶來判斷預期格式。宣告式結構專案會從 supabase/schemas/ 產生遷移;請參閱下方的「進行與提交結構變更」。

版本檢查與升級: 執行 supabase --version 檢查。如需 CLI 變更記錄和特定版本的功能,請查閱 CLI 文件 或 GitHub 發行頁面。

Supabase MCP 伺服器

有關設定說明、伺服器 URL 和組態,請參閱 MCP 設定指南。

連線問題疑難排解 — 請依序執行以下步驟:

  1. 檢查伺服器是否可達: curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp 401 是預期的(無權杖),表示伺服器正在執行。逾時或「connection refused」表示伺服器可能已關閉。

  2. 檢查 .mcp.json 組態: 驗證專案根目錄是否包含有效的 .mcp.json 且伺服器 URL 正確。如果遺失,請建立一個指向 https://mcp.supabase.com/mcp 的檔案。

  3. 驗證 MCP 伺服器: 如果伺服器可達且 .mcp.json 正確,但工具未顯示,則使用者需要進行驗證。Supabase MCP 伺服器使用 OAuth 2.1 — 告訴使用者在他們的代理中觸發驗證流程,在瀏覽器中完成,然後重新載入 session。 在 CI 或其他無法執行瀏覽器流程的環境中,請改為在 Authorization: Bearer 標頭中傳遞一個範圍限定個人存取權杖。

  4. 檢查範圍限定權杖權限: 如果使用範圍限定個人存取權杖時工具失敗,並顯示「You do not have permission to perform this action」,則表示該權杖缺少該工具的權限,或該專案超出了權杖的範圍。請在個人存取權杖指南中檢查該工具所需的權限。

Supabase 文件

在實作任何 Supabase 功能之前,請查閱相關文件。請依優先順序使用以下方法:

  1. MCP search_docs 工具(首選——直接回傳相關片段)
  2. 以 Markdown 格式擷取文件頁面——任何文件頁面都可以透過在 URL 路徑後附加 .md 來擷取。
  3. 針對 Supabase 特定主題進行網路搜尋,當你不知道該查閱哪個頁面時。

進行與提交結構變更

首先決定專案使用哪種結構工作流程。

選項 A:宣告式結構

當 supabase/schemas/ 存在或 config.toml 設定了 schema_paths 時使用此選項。編輯這些檔案中的期望結構狀態,然後產生並檢閱遷移。請勿從手動編寫遷移開始。請參閱宣告式資料庫結構指南。

選項 B:指令式遷移

當專案未使用宣告式結構時使用此選項。

若要進行結構變更,請使用 execute_sql(MCP)或 supabase db query(CLI)。 這些方法會直接對資料庫執行 SQL,而不會建立遷移歷史記錄條目,因此你可以自由迭代,並在準備好時產生一個乾淨的遷移。

請勿使用 apply_migration 來變更本地資料庫結構——它會在每次呼叫時寫入一個遷移歷史記錄條目,這表示你無法迭代,且 supabase db diff / supabase db pull 將產生空白的或衝突的差異。如果你使用它,你將被困在第一次嘗試時傳入的任何 SQL 中。

準備好提交你的變更到遷移檔案時:

  1. 執行 advisors → supabase db advisors(CLI v2.81.3+)或 MCP get_advisors。修正任何問題。
  2. 如果您的變更涉及檢視表、函數、觸發器或儲存空間,請檢閱上述的安全檢查清單。
  3. 產生遷移 → supabase db pull <描述性名稱> --local --yes
  4. 驗證 → supabase migration list --local

除錯

當你在 Supabase 相關請求上遇到錯誤時,例如來自 Supabase REST API、Postgres 資料庫或 PostgREST 的錯誤碼、結果為空、意外被 RLS 封鎖,或來自 Auth、Realtime、Edge Functions 或 Storage 等 Supabase 服務的錯誤,你必須在診斷或提出修正之前查閱 Supabase 的監控與除錯文件,而不是根據記憶來處理。同一份文件也涵蓋了效能最佳化,例如慢查詢和遺失的索引。

參考指南

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能