Next.js前端与Nest.js后端Socket.io连接CORS错误排查求助

问题分析 #

你遇到的CORS错误，核心原因大概率是WebSocket握手阶段的预检请求未被正确允许，或是前后端Socket.io版本不兼容，导致浏览器拦截了连接请求。Postman能正常连接是因为它不会严格遵循浏览器的CORS策略。

修复方案 #

1. 补充后端CORS的OPTIONS方法 #

WebSocket握手会先发OPTIONS预检请求，你的后端配置仅允许GET和POST，缺少OPTIONS方法，这是最常见的触发原因。

修改后端@WebSocketGateway的CORS配置：

@WebSocketGateway({
    namespace: 'chat',
    cors: {
        origin: ['http://localhost:3000'],
        methods: ['GET', 'POST', 'OPTIONS'], // 新增OPTIONS方法
        credentials: true,
        allowedHeaders: "*", // 本地开发可放开所有请求头
    },
})

2. 确保前后端Socket.io版本一致 #

Socket.io客户端与服务端版本必须严格匹配，版本差异会导致握手逻辑不兼容，表现为CORS错误。

• 查看后端package.json中@nestjs/platform-socket.io依赖的socket.io版本
• 查看前端package.json中socket.io-client的版本
• 确保两者版本完全相同（比如都用4.7.2这类稳定版）

3. 优化前端连接配置 #

添加错误监听和明确传输方式，帮助排查问题：

import { io, Socket } from "socket.io-client";

const SOCKET_URL = "http://localhost:4000/chat";

let socket: Socket | null = null;

export const getSocket = (): Socket => {
  if (!socket) {
    socket = io(SOCKET_URL, {
      withCredentials: true,
      transports: ['websocket', 'polling'], // 优先使用WebSocket传输
      reconnectionAttempts: 5,
    });
  }

  // 新增错误监听，打印具体错误信息
  socket.on("connect_error", (err) => {
    console.error("WebSocket连接失败:", err.message);
  });

  socket.on("connect", () => {
    console.log("已连接到WebSocket服务器，ID:", socket.id);
  });

  return socket;
};

4. 全局CORS配置对齐（可选） #

如果上述修改无效，检查Nest.js主应用的全局CORS配置，确保与WebSocket网关的规则一致：

// main.ts
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.enableCors({
    origin: ['http://localhost:3000'],
    methods: ['GET', 'POST', 'OPTIONS'],
    credentials: true,
  });
  await app.listen(4000);
}
bootstrap();

排查辅助步骤 #

1. 打开浏览器开发者工具，查看网络标签下的WebSocket请求，检查响应头是否包含Access-Control-Allow-Origin: http://localhost:3000和Access-Control-Allow-Credentials: true
2. 查看控制台的具体错误提示，定位是缺少请求头、方法不允许还是版本不兼容问题

内容的提问来源于stack exchange，提问作者Shafayet Ullah