NestJS网关Guard中无法向Socket添加用户数据问题排查

1. handleConnection 不支持 @UseGuards 装饰器 #

NestJS 的 OnGatewayConnection 生命周期钩子方法（即 handleConnection）不会触发 Guard。你在这个方法上加 @UseGuards 完全无效，所以连接建立时Guard从未执行，socket自然不会有user属性。

如果要在连接阶段验证并添加用户数据，要么手动在handleConnection里调用Guard的canActivate方法，要么直接把认证逻辑写在该方法内。

2. handleMessage 中属性不显示的问题 #

（1）Guard 执行验证 #

Guard会在@SubscribeMessage装饰的方法执行前运行，理论上socket.user应该存在。你可以先在Guard的canActivate里加日志，确认Guard是否在触发message事件时正常执行：

canActivate(context: ExecutionContext): boolean | Promise<boolean> | Observable<boolean> {
  console.log('Guard已执行'); // 验证触发时机
  // 省略用户数据获取逻辑
  const socket = context.switchToWs().getClient<Socket>();
  socket.user = new User(userId);
  return true;
}

（2）扩展Socket类型解决TypeScript报错 #

默认的Socket类型（来自socket.io）没有user属性，所以编辑器会提示属性不存在，但运行时实际是存在的。要让TypeScript识别这个自定义属性，创建类型声明文件（比如src/types/socket.d.ts）：

import { User } from '../path/to/user.entity'; // 替换为你的User类路径

declare module 'socket.io' {
  interface Socket {
    user: User;
  }
}

完整修正示例 #

修正后的Guard #

@Injectable()
export class MySocketAuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean | Promise<boolean> | Observable<boolean> {
    // 补充你的用户获取逻辑，比如从请求头解析token得到userId
    const userId = 'user_123'; // 示例值
    const socket = context.switchToWs().getClient<Socket>();
    socket.user = new User(userId);
    return true;
  }
}

修正后的网关 #

export class ChannelGateway implements OnGatewayConnection, OnGatewayDisconnect {
  constructor(private readonly authGuard: MySocketAuthGuard) {}

  // 手动处理连接时的认证
  async handleConnection(@ConnectedSocket() socket: Socket) {
    // 直接在这里实现认证逻辑，比如从握手信息取token
    const token = socket.handshake.headers.authorization?.split(' ')[1];
    const user = await this.validateToken(token); // 你的token验证方法
    socket.user = user;
    console.log(socket.user);
  }

  @UseGuards(MySocketAuthGuard)
  @SubscribeMessage('message')
  async handleMessage(@ConnectedSocket() socket: Socket) {
    console.log(socket.user); // 现在运行时可正常获取，TypeScript也无报错
  }

  // 示例token验证方法
  private async validateToken(token: string): Promise<User> {
    // 实现你的token解析、用户查询逻辑
    return new User('user_123');
  }
}

关键注意点 #

• 生命周期钩子（handleConnection、handleDisconnect）不支持Guard装饰器，必须手动处理认证。
• 扩展Socket类型是为了消除TypeScript的类型错误，不影响运行时属性的存在。
• 始终通过日志验证Guard的执行时机，确认逻辑是否按预期触发。

内容的提问来源于stack exchange，提问作者Eddy Freeman