NestJS WebSocket连接异常：无法建立连接或接收数据

核心原因 #

你遇到的连接失败问题，本质是Socket.IO 并非原生 WebSocket 协议——它在原生WebSocket之上封装了自己的握手流程、命名空间、房间等机制。直接用浏览器原生WebSocket对象或ws库发起连接，会因为缺少Socket.IO要求的握手步骤被服务端拒绝，导致连接重置。

解决方案一：使用Socket.IO官方客户端连接（推荐） #

既然服务端用的是Socket.IO网关，最直接的方式是用对应版本的Socket.IO客户端建立连接：

浏览器端连接示例 #

// 先引入Socket.IO客户端（可通过CDN或npm安装）
<script src="https://cdn.socket.io/4.7.2/socket.io.min.js"></script>
<script>
  // 连接服务端，Socket.IO会自动处理握手和路径
  const socket = io('http://localhost:3000', {
    transports: ['websocket'] // 指定只用WebSocket传输
  });

  socket.on('connect', () => {
    console.log('连接成功，客户端ID：', socket.id);
  });

  socket.on('disconnect', () => {
    console.log('连接断开');
  });
</script>

Node.js端连接示例 #

先安装Socket.IO客户端：

npm install socket.io-client@4.7.2

然后编写连接代码：

const { io } = require('socket.io-client');

const socket = io('http://localhost:3000', {
  transports: ['websocket']
});

socket.on('connect', () => {
  console.log('WebSocket连接已打开，客户端ID：', socket.id);
});

socket.on('disconnect', () => {
  console.log('WebSocket连接已关闭');
});

解决方案二：调整网关支持原生WebSocket（若必须用原生客户端） #

如果业务需求必须使用原生WebSocket协议，需要改用NestJS的原生WebSocket网关（基于@nestjs/platform-ws），而不是Socket.IO网关：

1. 安装依赖 #

npm install @nestjs/platform-ws ws

2. 修改网关代码 #

import {
  WebSocketGateway,
  WebSocketServer,
  OnGatewayConnection,
  OnGatewayDisconnect,
  SubscribeMessage,
} from '@nestjs/websockets';
import { Server } from 'ws';

// 原生WebSocket网关，默认监听路径为/
@WebSocketGateway({ path: '/' })
export class KoliWebSocketGateway implements OnGatewayConnection, OnGatewayDisconnect {
  @WebSocketServer() server: Server;

  handleConnection(client: any) {
    console.log(`客户端连接：${client._socket.remoteAddress}`);
    // 给客户端发送欢迎消息
    client.send('连接成功');
  }

  handleDisconnect(client: any) {
    console.log(`客户端断开连接：${client._socket.remoteAddress}`);
  }

  // 监听客户端消息
  @SubscribeMessage('message')
  handleMessage(client: any, payload: string) {
    console.log('收到消息：', payload);
    client.send(`收到你的消息：${payload}`);
  }
}

3. 更新main.ts配置 #

替换IoAdapter为WsAdapter：

import { WsAdapter } from '@nestjs/platform-ws';

// ...其他代码
app.useWebSocketAdapter(new WsAdapter(app));
// ...其他代码

此时你就可以用浏览器原生new WebSocket('ws://localhost:3000')或ws库正常连接了。

额外检查点 #

• 确认网关已正确导入到AppModule的providers数组中，NestJS会自动初始化网关。
• 跨域场景下，确保CORS配置允许WebSocket请求（Socket.IO客户端会自动处理，原生WS需保证enableCors包含对应Origin）。
• 版本兼容性：Socket.IO客户端与服务端版本需匹配（你的服务端用4.7.2，客户端用4.x版本即可）。

内容的提问来源于stack exchange，提问作者Tony Stark