Supabase

核心原则

1. Supabase迭代非常频繁——实现前请对照当前官方文档验证。 不要依赖训练数据中的Supabase功能信息，函数签名、config.toml配置、API约定会随版本发生变化。实现功能前，请通过下文的文档访问方法查询相关主题。

2. 验证你的工作成果。 完成任何修复后，请运行测试查询确认变更生效，未经验证的修复是不完整的。

3. 从错误中恢复，不要循环重试。 如果某一方法尝试2-3次后仍然失败，请停下重新评估。尝试其他方案、查阅文档、仔细排查错误，如有相关日志请优先查看。重复执行相同命令通常无法解决Supabase问题，虽然答案不一定都在日志里，但操作前检查日志往往是值得的。

4. 暴露schema默认开启RLS。 所有暴露schema下的表都要启用RLS，尤其是

public

schema。这一点在Supabase中至关重要，因为暴露schema下的表可以通过Data API直接访问。私有schema也建议开启RLS作为深度防御。开启RLS后，要创建符合实际访问模型的策略，不要给所有表都默认套用相同的

auth.uid()

模板。

5. 安全检查清单 处理任何涉及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
  或密钥。前端代码请优先使用可发布密钥，旧版
```
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策略，更新操作会静默返回0行——没有报错，也不会产生任何变更。
- 不要将
  security definer
  函数放在暴露的schema中。请将这类函数存放在私有或其他未暴露的schema下。
存储访问控制
- 存储upsert操作需要INSERT + SELECT + UPDATE三个权限。 仅授予INSERT权限允许新文件上传，但文件替换（upsert）会静默失败，你需要同时授予三个权限。

如有上文未覆盖的安全问题，请查阅Supabase产品安全索引：

https://supabase.com/docs/guides/security/product-security.md

Supabase CLI

永远通过

--help

查询命令用法——不要猜测。CLI结构会随版本发生变化。

bash

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
```
作为替代
当你需要新建迁移SQL文件时，必须先通过
```
supabase migration new <name>
```
创建。不要自定义迁移文件名，也不要凭记忆编写迁移文件格式。

版本检查与升级： 运行

supabase --version

查看当前版本。如需了解CLI变更日志和版本专属功能，请查阅CLI文档或GitHub releases。

Supabase MCP服务器

如需了解配置说明、服务器地址、参数设置，请查看MCP配置指南。

连接问题排查 —— 请按以下顺序操作：

检查服务器是否可达：
```
curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp
```
返回
```
401
```
属于预期结果（无token），说明服务器正常运行。返回超时或「连接拒绝」说明服务器可能已宕机。
检查
.mcp.json
配置：确认项目根目录下存在有效的
```
.mcp.json
```
文件，且服务器地址配置正确。如果文件不存在，请创建文件并配置地址为
```
https://mcp.supabase.com/mcp
```
。
认证MCP服务器： 如果服务器可达且
```
.mcp.json
```
配置正确，但工具仍无法正常显示，说明用户需要完成认证。Supabase MCP服务器使用OAuth 2.1协议——请告知用户在Agent中触发认证流程，在浏览器中完成认证后重载会话即可。

Supabase文档

实现任何Supabase功能前，请先查找相关文档。请按以下优先级选择查询方式：

MCP
search_docs
工具（优先使用——可直接返回相关文档片段）
拉取markdown格式的文档页面 —— 任何文档页面的URL后追加
```
.md
```
即可获取markdown格式内容。
不清楚对应文档页面时，可通过网页搜索查询Supabase相关主题。

创建与提交Schema变更

如需修改Schema，请使用
execute_sql
（MCP）或
supabase db query
（CLI）。这两个工具会直接在数据库运行SQL，不会创建迁移历史记录，因此你可以自由迭代，最终准备就绪后生成干净的迁移文件。

不要使用

apply_migration

修改本地数据库Schema——该命令每次调用都会写入一条迁移历史记录，导致你无法迭代修改，后续执行

supabase db diff

supabase db pull

会生成空的或冲突的diff。如果使用了该命令，你只能保留第一次传入的SQL内容，无法再调整。

准备好将变更提交到迁移文件时：

运行检查工具 →
```
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 当用户反馈本技能提供了错误指导或信息缺失时必须阅读此文档。

supabase

NPX安装

标签

SKILL.md 内容（中文）