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 聲明在使用者的權杖刷新之前並非總是最新的。
- 切勿在基於 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 預設為每個新函數授予PUBLICEXECUTE權限,因此public中的任何SECURITY DEFINER函數都是一個公開的 API 端點,可由anon和authenticated(從PUBLIC繼承)存取,無需任何額外授權。當確實需要SECURITY DEFINER時(例如繞過內部查詢表的 RLS),請將函數保留在未暴露的結構中,始終在函數體內包含auth.uid()檢查,並在進行變更後執行supabase db advisors。
- 檢視表預設繞過 RLS。 在 Postgres 15 及以上版本中,使用
-
儲存空間存取控制
- 儲存空間的 upsert 需要 INSERT + SELECT + UPDATE。 僅授予 INSERT 允許新上傳,但檔案替換(upsert)會無聲地失敗。你需要全部三個權限。
-
依賴項與供應鏈安全性
- 安裝 Supabase 套件(
supabase-js、@supabase/ssr、supabase-py等)時,請務必鎖定套件版本並提交鎖定檔案。 請參閱 npm 安全指南 了解完整檢查清單。
- 安裝 Supabase 套件(
對於上述未涵蓋的任何安全問題,請查閱 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+ → 改為使用 MCPexecute_sql或psql作為備用方案supabase db advisors需要 CLI v2.81.3+ → 改為使用 MCPget_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 設定指南。
連線問題疑難排解 — 請依序執行以下步驟:
-
檢查伺服器是否可達:
curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp401是預期的(無權杖),表示伺服器正在執行。逾時或「connection refused」表示伺服器可能已關閉。 -
檢查
.mcp.json組態: 驗證專案根目錄是否包含有效的.mcp.json且伺服器 URL 正確。如果遺失,請建立一個指向https://mcp.supabase.com/mcp的檔案。 -
驗證 MCP 伺服器: 如果伺服器可達且
.mcp.json正確,但工具未顯示,則使用者需要進行驗證。Supabase MCP 伺服器使用 OAuth 2.1 — 告訴使用者在他們的代理中觸發驗證流程,在瀏覽器中完成,然後重新載入 session。 在 CI 或其他無法執行瀏覽器流程的環境中,請改為在Authorization: Bearer標頭中傳遞一個範圍限定個人存取權杖。 -
檢查範圍限定權杖權限: 如果使用範圍限定個人存取權杖時工具失敗,並顯示「You do not have permission to perform this action」,則表示該權杖缺少該工具的權限,或該專案超出了權杖的範圍。請在個人存取權杖指南中檢查該工具所需的權限。
Supabase 文件
在實作任何 Supabase 功能之前,請查閱相關文件。請依優先順序使用以下方法:
- MCP
search_docs工具(首選——直接回傳相關片段) - 以 Markdown 格式擷取文件頁面——任何文件頁面都可以透過在 URL 路徑後附加
.md來擷取。 - 針對 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 中。
準備好提交你的變更到遷移檔案時:
- 執行 advisors →
supabase db advisors(CLI v2.81.3+)或 MCPget_advisors。修正任何問題。 - 如果您的變更涉及檢視表、函數、觸發器或儲存空間,請檢閱上述的安全檢查清單。
- 產生遷移 →
supabase db pull <描述性名稱> --local --yes - 驗證 →
supabase migration list --local
除錯
當你在 Supabase 相關請求上遇到錯誤時,例如來自 Supabase REST API、Postgres 資料庫或 PostgREST 的錯誤碼、結果為空、意外被 RLS 封鎖,或來自 Auth、Realtime、Edge Functions 或 Storage 等 Supabase 服務的錯誤,你必須在診斷或提出修正之前查閱 Supabase 的監控與除錯文件,而不是根據記憶來處理。同一份文件也涵蓋了效能最佳化,例如慢查詢和遺失的索引。
參考指南
- 技能回饋 → references/skill-feedback.md 當使用者回報此技能提供了錯誤的指導或遺漏資訊時,必須閱讀。