Supabase
核心原则
1. Supabase 变更频繁——在实施前务必对照变更日志和当前文档进行验证。 不要依赖训练数据中的 Supabase 功能。函数签名、config.toml 设置和 API 约定会随版本变化。
首先,获取 https://supabase.com/changelog.md(一个轻量级摘要索引——非重量级拉取),扫描与您的任务相关的 breaking-change 标签,并按照链接页面处理任何适用的变更。然后使用下面的文档访问方法查找相关主题。
2. 验证您的工作。 完成任何修复后,运行测试查询以确认更改有效。未经验证的修复是不完整的。
3. 从错误中恢复,不要循环。 如果一种方法在尝试 2-3 次后仍失败,请停下来重新考虑。尝试不同的方法,检查文档,更仔细地检查错误,并在可用时查看相关日志。Supabase 问题并非总能通过重试相同命令解决,答案也并不总是在日志中,但在继续之前检查日志通常值得一试。
4. 向数据 API 公开表: 取决于用户的数据 API 设置,新创建的表可能不会通过数据 (REST) API 自动公开。如果是这种情况,则需要显式授予 anon 和 authenticated 角色访问权限。
注意,这不同于 RLS,RLS 控制的是表可访问后哪些_行_可见,而不是表是否可访问。
当用户报告通过 SQL 创建的表意外不可访问时,请检查其数据 API 设置以及是否通过显式的 GRANT SQL 授予了角色访问权限。在授予公共(anon/authenticated)访问权限时,也要启用 RLS。有关完整的设置工作流,请参阅向数据 API 公开表。
5. 公开架构中的 RLS。
在任何公开架构(默认包括 public)的每个表上启用 RLS。这在 Supabase 中至关重要,因为当 anon/authenticated 角色拥有访问权限时,公开架构中的表可以通过数据 API 访问(请参阅向数据 API 公开表)。对于私有架构,建议将 RLS 作为纵深防御。启用 RLS 后,创建与实际访问模型匹配的策略,而不是将每个表默认设置为相同的 auth.uid() 模式。
6. 安全检查清单。 处理任何涉及认证、RLS、视图、存储或用户数据的 Supabase 任务时,请运行此检查清单。这些是 Supabase 特有的安全陷阱,会悄无声息地造成漏洞:
-
认证和会话安全
- 切勿在基于 JWT 的授权决策中使用
user_metadata声明。 在 Supabase 中,raw_user_meta_data是用户可编辑的,并且可能出现在auth.jwt()中,因此对于 RLS 策略或任何其他授权逻辑来说是不安全的。请将授权数据存储在raw_app_meta_data/app_metadata中。 - 删除用户不会使现有的访问令牌失效。 首先登出或撤销会话,对敏感应用保持较短的 JWT 过期时间,对于严格保证,在敏感操作上针对
auth.sessions验证session_id。 - 如果您使用
app_metadata或auth.jwt()进行授权,请记住 JWT 声明在用户令牌刷新之前并非始终是最新的。
- 切勿在基于 JWT 的授权决策中使用
-
API 密钥和客户端暴露
- 切勿在公共客户端中暴露
service_role或密钥。 在前端代码中优先使用可发布密钥。遗留的anon密钥仅用于兼容性。在 Next.js 中,任何NEXT_PUBLIC_环境变量都会被发送到浏览器。
- 切勿在公共客户端中暴露
-
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'会静默失效,因为匿名用户携带authenticatedPostgres 角色,无论用户是否真正登录都会通过检查。-- 已弃用(请勿使用) 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函数都是可由anon和authenticated(从PUBLIC继承)调用的公共 API 端点,无需额外授权。当确实需要SECURITY DEFINER时(例如,绕过内部查找表上的 RLS),请将函数保存在未公开的架构中,务必在函数体内包含auth.uid()检查,并在更改后运行supabase db advisors。
- 默认情况下,视图会绕过 RLS。 在 Postgres 15 及以上版本中,使用
-
存储访问控制
- 存储的 upsert 需要 INSERT + SELECT + UPDATE。 仅授予 INSERT 允许新上传,但文件替换(upsert)会静默失败。您需要所有这三个权限。
对于上述未涵盖的任何安全问题,请获取 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作为备选- 当您需要新的迁移 SQL 文件时,始终先用
supabase migration new <name>创建它。永远不要自己发明迁移文件名或依赖记忆来获取预期格式。
版本检查和升级: 运行 supabase --version 进行检查。有关 CLI 变更日志和特定版本功能,请查阅 CLI 文档 或 GitHub 发布。
Supabase MCP 服务器
有关设置说明、服务器 URL 和配置,请参阅 MCP 设置指南。
排查连接问题——按顺序执行以下步骤:
-
检查服务器是否可达:
curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp返回401是预期行为(无令牌)且表示服务器已启动。超时或“连接被拒绝”表示服务器可能已关闭。 -
检查
.mcp.json配置: 验证项目根目录存在一个有效的.mcp.json文件,其中包含正确的服务器 URL。如果缺失,请创建一个指向https://mcp.supabase.com/mcp的文件。 -
认证 MCP 服务器: 如果服务器可达且
.mcp.json正确,但工具不可见,则用户需要进行身份验证。Supabase MCP 服务器使用 OAuth 2.1 — 告诉用户在其代理中触发认证流程,在浏览器中完成,然后重新加载会话。
Supabase 文档
在实现任何 Supabase 功能之前,找到相关的文档。按优先顺序使用以下方法:
- MCP
search_docs工具(首选——直接返回相关代码片段) - 以 Markdown 格式获取文档页面——任何文档页面都可以通过在 URL 路径后附加
.md来获取。 - 网页搜索针对 Supabase 特定主题,当您不知道要查看哪个页面时。
制作和提交架构变更
要进行架构变更,请使用 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 <descriptive-name> --local --yes - 验证 →
supabase migration list --local
参考指南
- 技能反馈 → references/skill-feedback.md 当用户报告本技能提供了错误指导或缺失信息时,必须阅读