name: supabasedescription: “在涉及 Supabase 的任何任务时使用。触发条件Supabase 产品数据库、Auth、边缘函数、实时、存储、向量、定时任务、队列Next.js、React、SvelteKit、Astro、Remix 中的客户端库和 SSR 集成supabase-js、supabase/ssr认证问题登录、注销、……”risk: criticalsource: https://github.com/supabase/agent-skills/tree/main/skills/supabasesource_repo: supabase/agent-skillssource_type: officialdate_added: 2026-07-01license: MITlicense_source: https://github.com/supabase/agent-skills/blob/main/LICENSESupabase何时使用在涉及 Supabase 的任何任务时使用。触发条件Supabase 产品数据库、Auth、边缘函数、实时、存储、向量、定时任务、队列Next.js、React、SvelteKit、Astro、Remix 中的客户端库和 SSR 集成supabase-js、supabase/ssr认证问题登录、注销、……核心原则1. Supabase 变化频繁——实现前对照变更日志和当前文档验证。不要依赖训练数据来了解 Supabase 功能。函数签名、config.toml 设置和 API 约定会随版本变化。首先获取https://supabase.com/changelog.md一个轻量级摘要索引——不是重负载拉取扫描与你任务相关的breaking-change标签并跟随适用的链接页面。然后使用下面的文档访问方法查找相关主题。2. 验证你的工作。实现任何修复后运行一个测试查询以确认改动有效。未经验证的修复是不完整的。3. 从错误中恢复不要循环。如果一种方法在 2-3 次尝试后仍失败停下来重新考虑。尝试不同方法、查阅文档、更仔细地检查错误并在可用时审查相关日志。Supabase 的问题并不总是通过重试同一命令就能解决答案也不总在日志里但在继续之前检查日志通常值得一做。4. 向 Data API 暴露表取决于用户的 Data API 设置新建的表可能不会自动通过 DataRESTAPI 暴露。如果是这种情况需要显式授予anon和authenticated角色的访问权限。注意这不同于 RLSRLS 控制的是表可访问之后哪些_行_可见而不是表是否可访问。当用户报告一个通过 SQL 创建的表意外不可访问时检查他们的 Data API 设置以及是否通过显式GRANTSQL 授予了角色访问权限。在授予公共anon/authenticated访问时始终同时启用 RLS。完整的设置工作流参见 向 Data API 暴露表。5. 暴露 schema 中的 RLS。在任何暴露的 schema 中的每张表上都启用 RLS默认包括public。这在 Supabase 中至关重要因为当anon/authenticated角色有访问权限时暴露 schema 中的表可以通过 Data API 访问参见 向 Data API 暴露表。对于私有 schema建议使用 RLS 作为纵深防御。启用 RLS 后创建与真实访问模型匹配的策略而不是让每张表都默认使用相同的auth.uid()模式。6. 安全检查清单。在开展任何涉及 auth、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 声明在用户令牌刷新之前并不总是最新的。API 密钥和客户端暴露绝不在公共客户端中暴露service_role或密钥。前端代码优先使用可发布的密钥。旧版anon密钥仅用于兼容性。在 Next.js 中任何NEXT_PUBLIC_环境变量都会被发送到浏览器。RLS、视图和特权数据库代码视图默认绕过 RLS。在 Postgres 15 及以上版本中使用CREATE VIEW ... WITH (security_invoker true)。在较旧版本的 Postgres 中通过撤销anon和authenticated角色的访问权限或将视图放在未暴露的 schema 中来保护视图。UPDATE 需要 SELECT 策略。在 Postgres RLS 中UPDATE 需要先 SELECT 该行。没有 SELECT 策略更新会静默返回 0 行——没有错误只是没有变化。auth.role()已弃用——改用TO子句。Supabase 已弃用auth.role()改用直接在策略上用TO authenticated或TO anon指定目标角色。除了弃用之外当启用匿名登录时auth.role() authenticated会静默失效因为匿名用户携带authenticatedPostgres 角色无论用户是否真正登录都会通过检查。-- 已弃用不要使用createpolicyexampleontable_nameforselectusing(auth.role()authenticated);单独使用TO authenticated只是认证而非授权BOLA / IDOR。使用TO authenticated只检查角色——它不限制用户能访问哪些行。正确的模式是将TO authenticated与USING中的所有权谓词结合createpolicyexampleontable_nameforselecttoauthenticatedusing((selectauth.uid())user_id);UPDATE 策略需要同时有USING和WITH CHECK。没有WITH CHECK用户可以把行的user_id改给另一个用户createpolicyexampleontable_nameforupdatetoauthenticatedusing((selectauth.uid())user_id)withcheck((selectauth.uid())user_id);SECURITY DEFINER函数绕过 RLS。SECURITY DEFINER函数以其创建者的权限运行——通常是具有bypassrls的角色例如postgres。绝不要用添加SECURITY DEFINER来解决权限错误它会静默移除访问控制而不修复根本原因。优先使用SECURITY INVOKER。public中的SECURITY DEFINER函数可被所有角色调用。Postgres 默认授予每个新函数EXECUTE给PUBLIC因此public中任何SECURITY DEFINER函数都是一个公共 API 端点anon和authenticated继承自PUBLIC无需额外授权即可调用。当确实需要SECURITY DEFINER例如在内部查找表上绕过 RLS时把函数放在未暴露的 schema 中始终在函数体内包含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.mdSupabase CLI始终通过--help发现命令——绝不要猜测。CLI 结构随版本变化。supabase--help# 所有顶级命令supabasegroup--help# 子命令例如 supabase db --helpsupabasegroupcommand--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/mcp401是预期的无令牌且表示服务器已启动。超时或connection refused表示服务器可能宕机。检查.mcp.json配置验证项目根目录有有效的.mcp.json且服务器 URL 正确。如果缺失创建一个指向https://mcp.supabase.com/mcp的。认证 MCP 服务器如果服务器可达且.mcp.json正确但工具不可见用户需要认证。Supabase MCP 服务器使用 OAuth 2.1——告诉用户在他们的代理中触发认证流程在浏览器中完成然后重新加载会话。Supabase 文档在实现任何 Supabase 功能之前找到相关文档。按优先级顺序使用这些方法MCPsearch_docs工具首选——直接返回相关片段以 markdown 形式获取文档页面—— 任何文档页面都可以通过在 URL 路径后追加.md来获取。Web 搜索Supabase 特定主题当你不知道应该看哪个页面时使用。进行和提交 schema 变更要进行 schema 变更使用execute_sqlMCP或supabase db queryCLI。这些直接对数据库运行 SQL不创建迁移历史记录条目因此你可以自由迭代并在准备好时生成干净的迁移。不要使用apply_migration来更改本地数据库 schema——它每次调用都会写入一个迁移历史记录条目这意味着你无法迭代且supabase db diff/supabase db pull会产生空 diff 或冲突的 diff。如果你用了它就会被第一次尝试传入的 SQL 卡住。准备好提交你的变更到迁移文件时运行 advisors→supabase db advisorsCLI v2.81.3或 MCPget_advisors。修复任何问题。审查上面的安全检查清单如果你的变更涉及视图、函数、触发器或存储。生成迁移→supabase db pull 描述性名称 --local --yes验证→supabase migration list --local参考指南技能反馈→ references/skill-feedback.md必须阅读当用户报告本技能给出了错误指导或缺少信息时。局限性仅当任务与其上游产品或 API 范围明确匹配时使用本技能。在做出变更之前对照当前官方文档验证命令、API 行为、定价、配额、凭据和部署影响。不要将生成的示例视为环境特定测试、安全审查或用户对破坏性或高成本操作批准流程的替代品。
