NestJS配置@Throttle(3,60)限流实际仅1次请求就触发429拦截

云上老周

2026-8-29

问题根因与修复方案

你遇到的限流阈值不生效问题，基本是以下几个常见配置错误导致的，按优先级排查即可：

ThrottlerGuard重复注册导致计数多倍累加
如果你已经在根模块通过APP_GUARD令牌全局注册了ThrottlerGuard，又在login路由上手动添加了@UseGuards(ThrottlerGuard)，同一个请求会触发多次限流计数逻辑。按你现在3次的阈值配置，如果守卫被重复注册3次，第一次请求正常走完流程时，计数已经被累加到阈值上限，第二次请求进来就会直接触发429拦截，和你描述的现象完全吻合。
修复方式：删除路由上手动挂载的@UseGuards(ThrottlerGuard)即可。全局注册的限流守卫会自动作用于所有路由，@Throttle()装饰器单独配置路由规则时不需要重复绑定守卫。
版本适配问题导致ttl单位/参数不匹配
@nestjs/throttler v4.0及以上版本中，ttl（时间窗口）的计数单位已经从秒调整为毫秒，你当前写的@Throttle(3, 60)在高版本里实际代表60毫秒内允许3次请求，和你预期的60秒窗口完全不符。另外部分版本直接传位置参数容易出现顺序混淆问题，也会导致阈值异常。
修复方式：优先用对象传参规避顺序、单位歧义，配置写法如下：
```
@Throttle({ default: { limit: 3, ttl: 60000 } })
```
其中60000就是60秒对应的毫秒值。
OPTIONS预检请求占用限流额度
Postman发送POST等非简单请求时，会自动发送OPTIONS方法的预检请求，如果限流规则没有配置忽略这类请求，预检请求会提前占用限流额度，导致你实际发送的业务请求还没到3次就被拦截。
修复方式：在ThrottlerModule的根配置里添加跳过逻辑，忽略OPTIONS请求计数，参考配置：
```
ThrottlerModule.forRoot({
  throttlers: [{
    limit: 3,
    ttl: 60000
  }],
  skipIf: (context) => {
    const req = context.switchToHttp().getRequest();
    return req.method === 'OPTIONS';
  }
})
```