SuperAPI AI 工具集

supabase

编程与开发

查看项目

更新于 10-16 06:40

技能介绍

Supabase 是一个后端即服务平台,本技能用于在涉及 Supabase 的任何任务中提供操作指导。

用途 该技能适用于所有与 Supabase 相关的任务,触发范围包括 Supabase 的各类产品:数据库(Database)、认证(Auth)、边缘函数(Edge Functions)、实时(Realtime)、存储(Storage)、向量(Vectors)、定时任务(Cron)和队列(Queues),以及客户端相关任务。

核心原则

  1. Supabase 变化频繁,实现前应核对当前文档。不要依赖训练数据中的 Supabase 功能信息,函数签名、config.toml 设置和 API 约定会随版本变化。实现前应通过文档访问方法查找相关主题。
  2. 验证工作成果。实现任何修复后,运行测试查询确认改动生效。未经验证的修复是不完整的。
  3. 从错误中恢复,不要循环重试。如果某种方法尝试 2-3 次后仍失败,应停下来重新考虑,尝试不同方法、查阅文档、更仔细地检查错误,并在可用时查看相关日志。Supabase 问题并非总能通过重复同一命令解决,答案也不总在日志中,但继续之前查看日志往往值得。
  4. 向数据 API 暴露表。根据用户的数据 API 设置,新建表可能不会自动通过数据(REST)API 暴露。若如此,需要显式授予 anon 和 authenticated 角色访问权限。注意这与 RLS 不同,RLS 控制表可访问后哪些行可见,而非表是否可访问。当用户报告通过 SQL 创建的表意外无法访问时,应检查其数据 API 设置以及是否通过显式 GRANT SQL 授予了角色访问权限。授予公共(anon/authenticated)访问时,务必同时启用 RLS。
  5. 暴露模式中的 RLS。在任何暴露模式(默认包括 public)的每张表上启用 RLS。这在 Supabase 中至关重要,因为当 anon/authenticated 角色有访问权限时,暴露模式中的表可通过数据 API 访问。对于私有模式,建议将 RLS 作为纵深防御。启用 RLS 后,应创建符合实际访问模型的策略,而不是将所有表默认设为相同的 auth.uid() 模式。
  6. 安全清单。处理任何涉及认证、RLS、视图、存储或用户数据的 Supabase 任务时,应逐项检查以下 Supabase 特有的安全陷阱:
  • 认证与会话安全:绝不在基于 JWT 的授权决策中使用 user_metadata 声明,因为 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),在更早版本中通过撤销 anon 和 authenticated 角色的访问权限或将视图放入未暴露模式来保护。UPDATE 需要 SELECT 策略,在 Postgres RLS 中 UPDATE 需先 SELECT 行,没有 SELECT 策略时更新会静默返回 0 行,无错误也无变化。不要将 security definer 函数放在暴露模式中,应放在私有或未暴露模式。
  • 存储访问控制:存储 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 <group> <command> --help 已知注意事项:supabase db query 需要 CLI v2.79.0+,否则使用 MCP execute_sql 或 psql 作为后备;supabase db advisors 需要 CLI v2.81.3+,否则使用 MCP get_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+)或 MCP get_advisors,修复任何问题;若更改涉及视图、函数、触发器或存储,回顾上述安全清单;生成迁移 → supabase db pull <descriptive-name> --local --yes;验证 → supabase migration list --local。

参考指南 技能反馈 → references/skill-feedback.md,当用户报告此技能给出错误指导或缺少信息时必须阅读。