用途：@upstash/ratelimit 在 Upstash Redis 之上实现分布式限流。由于状态存放在 Redis 中，每个无服务器函数或边缘 Worker 实例共享同一计数器，这是内存限流器做不到的。适用于需要跨多个无服务器实例或区域，按 IP、用户、API Key 或租户限制请求的场景，也用于保护登录、注册、表单、webhook 或 LLM 端点免遭滥用并返回 429 Too Many Requests。不适用于对第三方 API 限制作客户端重试/退避，也不适用于无共享状态的单一长驻进程（内存限流器更简单）。
主要能力：内置固定窗口、滑动窗口、令牌桶三种算法；支持按标识符分键、对已受限标识符做可选的内存阻断，以及可选分析统计。
使用方式：先执行 npm install @upstash/ratelimit @upstash/redis，并设置 UPSTASH_REDIS_REST_URL 与 UPSTASH_REDIS_REST_TOKEN 环境变量。限流器应在处理函数之外创建一次，例如导出 const ratelimit = new Ratelimit({ redis: Redis.fromEnv(), limiter: Ratelimit.slidingWindow(10, "10 s"), prefix: "rl:api", analytics: true })，以便内置临时缓存短路已达限的标识符。调用 const { success, limit, remaining, reset, pending } = await ratelimit.limit(userId)，success 为 false 表示超限，reset 为毫秒级 Unix 时间戳，pending 是分析、多区域同步等后台工作的 Promise，在边缘运行时需 await 或交给 waitUntil，避免函数在完成前被冻结。可在 Next.js 中间件中读取 IP 并返回 429，并附上 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 和 Retry-After 响应头。令牌桶可按套餐分别配置。
限制：必须使用 Upstash Redis，不支持其他 Redis 服务器或无网络环境；每次 limit() 至少一次 HTTP 往返，会给受保护请求增加延迟；滑动窗口是近似算法，假设上一窗口内请求均匀分布；MultiRegionRatelimit 以精度换延迟且不支持令牌桶；Redis 不可达时默认 5 秒超时后放行请求，属于失败开放。本技能不替代针对具体环境的验证、测试或专家审查。
安全提示：限流只是滥用防护的一层，不能代替认证，应与认证和输入校验配合；Redis 令牌拥有完整数据库访问权限，必须保存在服务端；生产环境收紧限流可能误锁正常用户，部署前需与用户确认数值。常见问题：标识符在各请求间必须是同一字符串；在 Vercel Edge 或 Cloudflare Workers 上分析数据为空时，需将 pending 传给 waitUntil。相关技能包括 @upstash-redis、@api-rate-limit-handler 和 @upstash-qstash。