supabase-best-practices

Supabase 最佳实践

为集成 Clerk 身份验证的 Supabase 应用提供全面的安全与性能优化指南。涵盖 10 个类别中的 40 多条规则，并按影响排序，帮助安全地开发和审查代码。

适用场景

在以下情况下参考这些指南：

• 设置新的 Supabase 项目
• 将 Clerk 身份验证集成到 Supabase
• 编写行级安全（RLS）策略
• 设计数据库架构
• 实现实时功能
• 配置 Storage 存储桶
• 编写 Edge Functions
• 审查代码中的安全问题

按优先级划分的规则类别

优先级	类别	影响	前缀
1	行级安全	CRITICAL	rls-
2	Clerk 集成	CRITICAL	clerk-
3	数据库安全	HIGH	db-
4	身份验证模式	HIGH	auth-
5	API 安全	HIGH	api-
6	Storage 安全	MEDIUM-HIGH	storage-
7	Realtime 安全	MEDIUM	realtime-
8	Edge Functions	MEDIUM	edge-
9	测试	MEDIUM	test-
10	安全	MEDIUM	security-

快速参考

1. 行级安全（CRITICAL）

• rls-always-enable - 始终为 public 架构中的表启用 RLS
• rls-wrap-functions-select - 使用 (SELECT ...) 包装身份验证函数以提升性能
• rls-add-indexes - 为 RLS 策略中使用的列添加索引
• rls-specify-roles - 使用 TO authenticated 子句指定角色
• rls-security-definer - 对复杂策略使用 SECURITY DEFINER 函数
• rls-minimize-joins - 尽量减少 RLS 策略中的联接
• rls-explicit-auth-check - 使用明确的 auth.uid() 检查
• rls-restrictive-policies - 使用 RESTRICTIVE 策略添加额外限制

2. Clerk 集成（CRITICAL）

• clerk-setup-third-party - 使用 Third-Party Auth 集成（而不是 JWT 模板）
• clerk-client-server-side - 对服务端客户端使用 accessToken 回调
• clerk-client-client-side - 对客户端使用 useSession() hook
• clerk-role-claim - 在 Clerk 中配置 role: authenticated 声明
• clerk-org-policies - 在多租户 RLS 中使用组织声明
• clerk-mfa-policies - 使用 RESTRICTIVE 策略强制执行 MFA
• clerk-no-jwt-templates - 切勿使用已弃用的 JWT 模板集成

3. 数据库安全（HIGH）

• db-migrations-versioned - 对架构变更使用带版本号的迁移
• db-schema-design - 遵循正确的架构设计模式
• db-indexes-strategy - 实施恰当的索引策略
• db-foreign-keys - 始终使用外键约束
• db-triggers-security - 妥善保护触发器函数
• db-views-security-invoker - 对视图使用 SECURITY INVOKER

4. 身份验证模式（HIGH）

• auth-jwt-claims-validation - 始终验证 JWT 声明
• auth-user-metadata-safety - 将 user_metadata 视为不可信数据
• auth-app-metadata-authorization - 使用 app_metadata 进行授权
• auth-session-management - 实施恰当的会话管理

5. API 安全（HIGH）

• api-filter-queries - 即使启用了 RLS，也始终过滤查询
• api-publishable-keys - 正确使用 publishable key
• api-service-role-server-only - 切勿向客户端暴露 service role key

6. Storage 安全（MEDIUM-HIGH）

• storage-rls-policies - 为 storage.objects 启用 RLS
• storage-bucket-security - 配置存储桶级别的安全性
• storage-signed-urls - 对私有文件使用签名 URL

7. Realtime 安全（MEDIUM）

• realtime-private-channels - 对敏感数据使用私有频道
• realtime-rls-authorization - RLS 策略适用于 Realtime
• realtime-cleanup-subscriptions - 卸载时清理订阅

8. Edge Functions（MEDIUM）

• edge-verify-jwt - 始终在 Edge Functions 中验证 JWT
• edge-cors-handling - 正确处理 CORS
• edge-secrets-management - 对敏感数据使用密钥

9. 测试（中等）

• test-pgtap-rls - 使用 pgTAP 测试 RLS 策略
• test-isolation - 正确隔离测试
• test-helpers - 使用测试辅助函数

10. 安全（中等）

• security-validate-inputs - 在处理前验证所有输入
• security-audit-advisors - 定期运行 Security Advisor 检查

使用方法

阅读各个规则文件，了解详细说明和代码示例：

references/rules/rls-always-enable.md
references/rules/clerk-setup-third-party.md
references/rules/_sections.md

每个规则文件都包含：

• 简要说明其重要性
• 错误代码示例及说明
• 正确代码示例及说明
• 不适用该模式的情况
• 官方文档的参考链接

完整汇编文档

完整指南（包含所有展开的规则）请参阅：references/supabase-guidelines.md