它能做什么
中文摘要
这是 Supabase 官方发布的 agent skill（仓库 supabase/agent-skills，版本 0.1.2），面向任何涉及 Supabase 的任务，覆盖 Database、Auth、Edge Functions、Realtime、Storage、Vectors、Cron、Queues 等产品，以及 supabase-js、@supabase/ssr 在 Next.js、React、SvelteKit、Astro、Remix 中的 SSR 集成。内容分几块：核心原则（不依赖训练数据、先查 changelog 与当前文档、实现后验证、失败 2-3 次即换思路、表暴露到 Data API 的 GRANT 与 RLS 关系）；一份 Supabase 专属安全清单（JWT 授权不能用 user_metadata、删除用户不失效 token、service_role 与密钥不得暴露、视图默认绕过 RLS、UPDATE 需要 SELECT 策略、auth.role() 已废弃且匿名登录下会失效、TO authenticated 单独使用构成 BOLA/IDOR、UPDATE 策略需 USING+WITH CHECK、SECURITY DEFINER 绕过 RLS 且 public 中默认可被调用、Storage upsert 需 INSERT+SELECT+UPDATE、锁定依赖版本）；CLI 使用规范（必须用 --help 发现命令，附已知版本门槛与踩坑）；MCP server 的连接排查步骤（可达性 curl、.mcp.json、OAuth 2.1 认证、scoped token 权限）；文档获取优先级（MCP search_docs、URL 加 .md、网络搜索）；schema 变更的声明式与命令式两条路径（并说明何时用 execute_sql 而非 apply_migration）；以及调试时必须先读 Monitoring and Debugging 文档。
为什么推荐
推荐理由
由 Supabase 官方维护，安装量约 29 万、周安装稳定在 1.1 万以上，是数据库类中权威度与覆盖面都很突出的选择。它的价值不在 API 速查，而在把 Supabase 特有的坑写成可执行约束：RLS 与 Data API 暴露的边界、BOLA/IDOR 与 SECURITY DEFINER 这类静默漏洞、CLI 与 MCP 的版本门槛和连接排查流程、声明式与命令式迁移的取舍。对于会长期维护 Supabase 项目的团队，能显著降低“照着记忆写 RLS 结果被打穿”或“反复重试同一条失败命令”的概率。
什么时候用
适用场景
- 在 Next.js、React、SvelteKit、Astro、Remix 中接入 supabase-js 或 @supabase/ssr，并处理登录、登出、会话、JWT、cookie、getSession/getUser/getClaims
- 设计或审查 RLS 策略，以及判断新建表为何没有自动暴露到 Data API、该如何给 anon/authenticated 授权
- 排查 Supabase 项目上的异常行为：HTTP/Postgres 错误码、RLS 意外拦截、permission denied、schema cache 问题、超时、Edge Function 崩溃、Realtime 断连、Storage 失败
- 通过 Supabase CLI 或 MCP server 执行 schema 变更、迁移与安全审计（db advisors、get_advisors、db pull、migration list）
- 对涉及 Auth、RLS、视图、Storage、用户数据的 Supabase 实现做安全自检，包括 service_role 暴露、用户可编辑的 user_metadata、视图绕过 RLS、SECURITY DEFINER 函数等陷阱
- 配置与排障 Supabase MCP server：检查服务可达性、修正 .mcp.json、完成 OAuth 2.1 认证、使用 scoped personal access token 并核对其权限
使用前先看
主要亮点
- 01
官方技能，metadata 标注 author 为 supabase、version 0.1.2，触发范围涵盖 Database、Auth、Edge Functions、Realtime、Storage、Vectors、Cron、Queues 及 supabase-js、@supabase/ssr 在主流前端框架中的 SSR 集成
- 02
要求实现前先拉取 https://supabase.com/changelog.md 并扫描 breaking-change 标记，明确“不要依赖训练数据”，因为函数签名、config.toml、API 约定会随版本变化
- 03
内置 Supabase 专属安全清单：JWT 授权不可用 user_metadata（应存 raw_app_meta_data/app_metadata）、删除用户不会使既有 access token 失效、service_role/secret key 不得进入公开客户端、NEXT_PUBLIC_ 变量会下发到浏览器
- 04
指出多个静默失效的 RLS 陷阱：视图默认绕过 RLS（Postgres 15+ 用 security_invoker = true）、UPDATE 需要 SELECT 策略否则静默返回 0 行、auth.role() 已废弃且匿名登录下会误通过、TO authenticated 单独使用构成 BOLA/IDOR、UPDATE 策略必须同时写 USING 与 WITH CHECK
- 05
说明 SECURITY DEFINER 会绕过 RLS，且 public 中新建函数默认对 PUBLIC 授予 EXECUTE，因此可被 anon/authenticated 直接调用；需要时应放在非暴露 schema 并在函数体内检查 auth.uid()，改完运行 supabase db advisors
- 06
CLI 部分要求一律用 --help 发现命令，并列出已知门槛：supabase db query 需 v2.79.0+、supabase db advisors 需 v2.81.3+，两者可回退到 MCP 的 execute_sql 与 get_advisors
- 07
给出 MCP server 的四步连接排查：用 curl 检查 https://mcp.supabase.com/mcp 是否返回 401（表示服务在线）、核对 .mcp.json、触发 OAuth 2.1 浏览器认证、在 CI 中用 Authorization: Bearer 传 scoped token 并核对其权限
- 08
区分声明式与命令式 schema 工作流：存在 supabase/schemas/ 或 config.toml 设置 schema_paths 时先生成再审查迁移；命令式项目用 execute_sql 或 supabase db query 迭代，并明确警告不要用 apply_migration 改本地 schema，否则产生空的或冲突的 diff
- 09
规定遇到 Supabase 相关报错（REST、Postgres/PostgREST 错误、空结果、RLS 意外拦截、Auth/Realtime/Edge Functions/Storage 报错）必须先取用 Monitoring and Debugging 文档再诊断，而不是凭记忆处理
原始文档
原文摘录
Supabase Core Principles **1. Supabase changes frequently — verify against changelog and current docs before implementing.**