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. 安全清单。 在处理任何涉及 auth、RLS、视图、存储或用户数据的 Supabase 任务时,请检查此清单。这些是 Supabase 特定的安全陷阱,会悄无声息地创建漏洞:
-
Auth 和会话安全
- 切勿在基于 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或 secret 密钥。 在前端代码中优先使用可发布的密钥。旧版anon密钥仅用于兼容性。在 Next.js 中,任何NEXT_PUBLIC_环境变量都会发送到浏览器。 - 对管理 API、CLI 和 MCP 服务器使用限定作用域的个人访问令牌。 经典的个人访问令牌携带用户对所有组织和项目的全部账户访问权限。对于脚本、CI 和代理,让用户创建一个限定范围的令牌,仅限于任务所需的组织、项目和权限。个人访问令牌指南列出了每个管理 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'会静默失效,因为匿名用户携带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函数都是一个公共 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/mcp预期返回401(无令牌),表示服务器已启动。超时或“连接被拒绝”表示服务器可能已关闭。 -
检查
.mcp.json配置: 验证项目根目录包含一个有效的.mcp.json且服务器 URL 正确。如果缺失,创建一个指向https://mcp.supabase.com/mcp的文件。 -
验证 MCP 服务器: 如果服务器可达且
.mcp.json正确,但工具不可见,用户需要认证。 Supabase MCP 服务器使用 OAuth 2.1 — 告诉用户在其代理中触发认证流程,在浏览器中完成,并重新加载会话。 在 CI 或其他无法运行浏览器流程的环境中,改为在Authorization: Bearer头中传递一个限定范围的个人访问令牌。 -
检查限定范围令牌的权限: 如果使用限定范围的个人访问令牌时工具失败并显示“您无权执行此操作”,则令牌缺少该工具的权限或项目超出了令牌的范围。在个人访问令牌指南中检查工具所需的权限。
Supabase 文档
在实施任何 Supabase 功能之前,找到相关的文档。按优先级顺序使用这些方法:
- MCP
search_docs工具(首选 — 直接返回相关片段) - 获取文档页面为 markdown — 任何文档页面都可以通过在 URL 路径后附加
.md来获取。 - Web 搜索 针对 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 阻止,或者来自 Supabase 服务(如 Auth、Realtime、Edge Functions 或 Storage)的错误,你必须获取 Supabase 的监控和调试文档,然后再诊断或提出修复建议,而不是凭记忆工作。相同的文档还涵盖了性能优化,例如慢查询和缺失索引。
参考指南
- 技能反馈 → references/skill-feedback.md 当用户报告此技能给出错误指导或缺少信息时,必须阅读