Communitygithub.com

Supabase 技能

用于处理任何涉及 Supabase 的任务。涵盖数据库、认证、Edge Functions、实时功能、存储、向量、定时任务、队列等;客户端库和 SSR 集成(如 Next.js、React、SvelteKit);以及调试和故障排除。

Supabase 技能 是什么?

该技能为开发者和 AI 代理提供了一个全面的指南,用于处理与 Supabase 相关的所有任务。它强调了几个关键原则:首先,Supabase 变化频繁,必须始终对照最新的变更日志和文档进行验证。其次,任何修复后都必须运行测试查询来验证其有效性。第三,如果一种方法在 2-3 次尝试后失败,应停止并重新考虑策略,而不是盲目循环。该技能深入介绍了如何安全地处理数据 API 和行级安全(RLS),包括细粒度权限和常见陷阱(例如,视图默认绕过 RLS,且 `auth.role()` 已弃用)。它还提供了一个详细的安全清单,涵盖认证、API 密钥暴露和存储访问控制。此外,该技能还指导用户使用 Supabase CLI(通过 `--help` 发现命令,注意已知的陷阱,如版本要求)和 MCP 服务器(用于设置和故障排除)。对于模式更改,它区分了声明式和命令式工作流,并推荐了最佳实践。最后,在诊断错误时,它强制要求查阅官方的监控和调试文档。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Futurists2023/tiktok/tree/HEAD/.agents/skills/supabase

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 声明在用户令牌刷新之前并不总是最新的。
  • 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' 会静默失效,因为匿名用户携带 authenticated Postgres 角色,无论用户是否真正登录都会通过检查。
      -- 已弃用(请勿使用)
      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。
  • 存储访问控制

    • 存储 upsert 需要 INSERT + SELECT + UPDATE。 仅授予 INSERT 允许新上传,但文件替换 (upsert) 会静默失败。你需要所有三种权限。
  • 依赖和供应链安全

    • 在安装 Supabase 包(supabase-js、@supabase/ssr、supabase-py 等)时,始终锁定包版本并提交锁文件。 有关完整的检查清单,请参阅 npm 安全指南。

对于上述未涵盖的任何安全问题,请获取 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+ → 使用 MCP execute_sql 或 psql 作为备选
  • supabase db advisors 需要 CLI v2.81.3+ → 使用 MCP get_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 设置指南。

排查连接问题 — 按以下顺序执行步骤:

  1. 检查服务器是否可达: curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp 预期返回 401(无令牌),表示服务器已启动。超时或“连接被拒绝”表示服务器可能已关闭。

  2. 检查 .mcp.json 配置: 验证项目根目录包含一个有效的 .mcp.json 且服务器 URL 正确。如果缺失,创建一个指向 https://mcp.supabase.com/mcp 的文件。

  3. 验证 MCP 服务器: 如果服务器可达且 .mcp.json 正确,但工具不可见,用户需要认证。 Supabase MCP 服务器使用 OAuth 2.1 — 告诉用户在其代理中触发认证流程,在浏览器中完成,并重新加载会话。 在 CI 或其他无法运行浏览器流程的环境中,改为在 Authorization: Bearer 头中传递一个限定范围的个人访问令牌。

  4. 检查限定范围令牌的权限: 如果使用限定范围的个人访问令牌时工具失败并显示“您无权执行此操作”,则令牌缺少该工具的权限或项目超出了令牌的范围。在个人访问令牌指南中检查工具所需的权限。

Supabase 文档

在实施任何 Supabase 功能之前,找到相关的文档。按优先级顺序使用这些方法:

  1. MCP search_docs 工具(首选 — 直接返回相关片段)
  2. 获取文档页面为 markdown — 任何文档页面都可以通过在 URL 路径后附加 .md 来获取。
  3. 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 中。

当准备将你的更改提交到迁移文件时:

  1. 运行 advisors → supabase db advisors (CLI v2.81.3+) 或 MCP get_advisors。解决任何问题。
  2. 如果更改涉及视图、函数、触发器或存储,请审查上述安全清单
  3. 生成迁移 → supabase db pull <描述性名称> --local --yes
  4. 验证 → supabase migration list --local

调试

当你在与 Supabase 相关的请求上遇到错误时,例如来自 Supabase REST API、Postgres 数据库或 PostgREST 的错误代码,空结果,意外被 RLS 阻止,或者来自 Supabase 服务(如 Auth、Realtime、Edge Functions 或 Storage)的错误,你必须获取 Supabase 的监控和调试文档,然后再诊断或提出修复建议,而不是凭记忆工作。相同的文档还涵盖了性能优化,例如慢查询和缺失索引。

参考指南

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能