无法连接NestJS WebSocket Gateway搭建的服务，求排查方向

以下是针对你遇到的原生WebSocket客户端无法连接NestJS Gateway问题的具体排查步骤：

• 确认Gateway默认传输协议
  NestJS的@WebSocketGateway()装饰器默认使用Socket.IO作为传输层，而非原生WebSocket协议。直接用new WebSocket('ws://localhost:3000')或wscat连接根路径会失败，因为Socket.IO有自己的握手机制和路径规则（默认路径是/socket.io/）。

• 验证Socket.IO客户端连接
  先用Socket.IO客户端测试连接，确认Gateway本身是否正常工作：

  // 浏览器控制台或Node.js环境
  import { io } from 'socket.io-client';
  const socket = io('http://localhost:3000');
  socket.on('connect', () => console.log('Connected via Socket.IO'));
  

  如果能正常连接，说明Gateway没问题，只是原生WebSocket客户端不兼容默认配置。

• 配置Gateway支持原生WebSocket
  若需要支持原生WebSocket，需安装@nestjs/platform-ws依赖，然后修改Gateway配置：

  import { WebSocketGateway, WebSocketServer } from '@nestjs/websockets';
  import { Server } from 'ws';
  
  @WebSocketGateway({
    transports: ['websocket'], // 指定使用原生WebSocket传输
    cors: true, // 按需开启CORS
  })
  export class MigrationGateway {
    @WebSocketServer()
    server: Server;
    // ... 你的连接、消息处理逻辑
  }
  

  同时在应用启动时绑定WebSocket适配器：

  import { NestFactory } from '@nestjs/core';
  import { AppModule } from './app.module';
  import { WsAdapter } from '@nestjs/platform-ws';
  
  async function bootstrap() {
    const app = await NestFactory.create(AppModule);
    app.useWebSocketAdapter(new WsAdapter(app));
    await app.listen(3000);
  }
  bootstrap();
  

  配置完成后，再用new WebSocket('ws://localhost:3000')或wscat测试连接。

• 检查CORS配置
  浏览器客户端连接时，若存在跨域问题会导致连接失败。在Gateway装饰器中显式配置CORS：

  @WebSocketGateway({
    cors: {
      origin: '*', // 生产环境建议指定具体域名
      credentials: true,
    },
  })
  

• 排查端口与路径冲突
  确认3000端口未被其他服务占用，且Gateway没有指定非默认路径（比如@WebSocketGateway({ path: '/custom-ws' })），如果有自定义路径，连接时需要加上对应路径：ws://localhost:3000/custom-ws。

• 开启详细日志排查请求
  在Gateway的连接/断开钩子中添加日志，确认服务器是否收到连接请求：

  import { OnGatewayConnection, OnGatewayDisconnect } from '@nestjs/websockets';
  
  export class MigrationGateway implements OnGatewayConnection, OnGatewayDisconnect {
    handleConnection(client: any) {
      console.log('Client connected:', client);
    }
  
    handleDisconnect(client: any) {
      console.log('Client disconnected:', client);
    }
  }
  

  同时可以开启NestJS的debug日志，在启动时添加--debug参数，查看更详细的框架运行日志。

内容的提问来源于stack exchange，提问作者Victor Shelepen