NestJS中Websocket的ThrottlerGuard无法使用报错

问题 #

在基于NestJS + Websocket的项目中，自定义了继承ThrottlerGuard的NewThrottlerGuard，并在Gateway的sendMessage方法上使用@UseGuards(NewThrottlerGuard)装饰器，触发如下错误：

Error: Invalid guard passed to @UseGuards() decorator (ChatGateway).

调试validateEach函数时发现传入的守卫实例为undefined。已知全局守卫方式不可用，改用方法级装饰器仍报错。

原因及修复方案 #

1. 循环引用导致守卫未初始化 #

这是最常见的触发原因：ChatGateway和NewThrottlerGuard之间存在循环导入，使得装饰器执行时NewThrottlerGuard还未被定义，最终传入@UseGuards的是undefined。

修复：

• 检查两个文件的导入语句，确认是否存在互相引用（比如网关导入守卫，守卫又导入网关或同模块的其他依赖）。
• 重构代码解耦：将共享逻辑抽离到独立工具类/服务，确保依赖关系单向。

2. 守卫未在模块Providers中注册 #

即使守卫标注了@Injectable()，若未添加到对应模块的providers数组中，Nest无法正确解析其实例，也会导致守卫无效。

修复：
在网关所在的模块（如ChatModule）中注册守卫：

@Module({
  providers: [ChatGateway, NewThrottlerGuard],
})
export class ChatModule {}

3. 版本兼容性问题 #

确保@nestjs/throttler版本与NestJS主版本匹配，部分旧版本对Websocket守卫的支持存在缺陷。

修复：

• 执行npm list @nestjs/core @nestjs/throttler查看版本，确保两者主版本一致（比如都是v10.x）。
• 若版本不匹配，升级或降级到兼容版本。

4. 守卫实现的细节优化 #

虽然你的handleRequest实现逻辑正确，但可以补充空值判断避免潜在的上下文解析问题：

protected async handleRequest(
  context: ExecutionContext,
  limit: number,
  ttl: number,
): Promise<boolean> {
  const wsContext = context.switchToWs();
  const client = wsContext.getClient<Socket>();
  
  if (!client?.conn?.remoteAddress) {
    throw new ThrottlerException('无法获取客户端标识');
  }
  
  const ip = client.conn.remoteAddress;
  const key = this.generateKey(context, ip);
  const ttls = await this.storageService.getRecord(key);

  if (ttls.length >= limit) {
    throw new ThrottlerException();
  }

  await this.storageService.addRecord(key, ttl);
  return true;
}

总结 #

优先排查循环引用和模块注册问题，这是导致守卫被识别为undefined的核心原因。若问题仍存在，检查版本兼容性或尝试在网关类上绑定守卫测试（@UseGuards(NewThrottlerGuard)加在Gateway类上），逐步定位问题。

内容的提问来源于stack exchange，提问作者Henrique Ramos