supabase-rate-limits

Supabase 速率限制

概述

Supabase 会对所有 API 接口（PostgREST、Auth、Storage、Realtime 和 Edge Functions）实施速率限制和配额，具体数值因套餐等级而异。本技能介绍各套餐等级的精确限制、通过 Supavisor 进行连接池管理、重试／退避与分页模式，以及仪表板监控，帮助你遵守配额并妥善处理 429 错误。

前提条件

• 有效的 Supabase 项目（任意套餐等级）
• 已安装 @supabase/supabase-js v2+
• 可用的项目 URL 和 anon/service-role 密钥
• Node.js 18+ 或等效运行时

操作说明

步骤 1 — 了解套餐等级限制

不同接口和套餐等级的速率限制各不相同。主要 API 限制如下：

指标	Free	Pro	Enterprise
每分钟请求数（RPM）	500	5,000	不限（自定义）
每日请求数（RPD）	50,000	1,000,000	不限（自定义）

Auth、Storage、Realtime、Edge Functions 和数据库连接各自都有配额。开始设计架构前，请参阅 rate-limit-tiers.md 中各接口的完整限制细目。

步骤 2 — 使用 Supavisor 连接池

Supavisor 是 Supabase 内置的连接池（已取代 PgBouncer）。根据工作负载选择模式：

用例	模式	端口
无服务器／Edge Functions	Transaction	6543
Next.js API 路由	Transaction	6543
长时间运行的工作进程	Session	5432
Realtime 订阅	Direct（无连接池）	5432
Prisma／Drizzle ORM	Transaction + ?pgbouncer=true	6543

Transaction 模式（端口 6543）会在每次事务完成后将连接归还连接池，是无服务器环境的默认选择。Session 模式（端口 5432）会保留专用连接，用于 LISTEN/NOTIFY 和预处理语句。完整的客户端设置和连接字符串格式请参阅 implementation.md。

步骤 3 — 重试、分页和批处理

使用能够识别 429 错误和连接池耗尽情况的指数退避重试机制包装查询：

// Retryable when the error is a rate limit, "too many requests",
// code 429, or PGRST000 (connection pool exhausted). Delay doubles
// per attempt with jitter, capped at maxDelayMs, honoring Retry-After.
const users = await withRetry(() =>
  supabase.from('users').select('id, email, created_at').eq('active', true)
)

然后通过两种方式减少请求量：使用 .range(from, to) 对大量读取进行分页，以缩小响应并避免超时；将 N 次写入合并为一次批量 upsert（每个请求最多约 1000 行，更大的数据集应分块处理）。完整的 withRetry、fetchPaginated 和批处理／chunk 辅助函数，以及仪表板监控步骤，请参阅 implementation.md。

输出

应用本技能后，你将获得：

• 清楚了解各套餐等级的速率限制（Free：500 RPM／50K RPD，Pro：5K RPM／1M RPD）
• 通过 Supavisor 配置连接池（无服务器环境使用端口 6543 的 Transaction 模式）
• 使用指数退避处理 429 错误的重试包装器
• 使用 .range(0, 99) 的分页查询，以缩小载荷
• 将 N 个请求减少为 1 个请求的批量 upsert 模式
• 配置仪表板监控并设置 API 使用量告警

错误处理

错误	原因	解决方案
429 Too Many Requests	超出 RPM 或 RPD 限制	应用 withRetry 退避策略；降低并发；升级套餐
PGRST000: could not connect	连接池耗尽	切换到 Supavisor 事务模式（端口 6543）；减少并发查询
Auth over_request_rate_limit	同一 IP 的注册或登录次数过多	添加 CAPTCHA；在 Dashboard 中配置自定义身份验证速率限制
Storage 413 Payload Too Large	文件超出套餐限制	使用 TUS 可续传上传；检查套餐的文件大小限制
Realtime too_many_connections	达到并发连接数限制	取消订阅未使用的频道；升级到 Pro，支持 500 个连接
Edge Function BOOT_ERROR	冷启动超时或超出内存限制	减小捆绑包大小；避免在顶层导入大型依赖
Prisma 出现 pgbouncer=true 错误	缺少连接字符串参数	在 6543 端口的连接池连接字符串末尾添加 ?pgbouncer=true

速率限制响应标头（X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset、Retry-After）及其对应的处理方法，请参阅 errors.md。

示例

• 带批量插入功能且能安全处理速率限制的无服务器 Edge Function 客户端 — 请参阅 examples.md
• 根据运行时选择连接字符串（无服务器、长时间运行或直接连接）— 请参阅 examples.md
• 基于队列的限流和客户端标头监控 — 请参阅 examples.md

资源

• Supabase 平台限制与配额
• Supavisor 连接池
• Edge Functions 限制
• Storage 限制
• @supabase/supabase-js 参考

后续步骤

如需通过 RLS 策略和 API 密钥管理来保护 Supabase 项目，请参阅 supabase-security-basics。如需优化数据库查询和索引，请参阅 supabase-performance-tuning。