Socket.IO "Error during WebSocket handshake: Unexpected response code: 404" in React browser

近日，大量 React 开发者反馈在浏览器环境下使用 Socket.IO 进行实时通信时，遇到“Error during WebSocket handshake: Unexpected response code: 404”错误。这一错误直接导致 WebSocket 连接失败，影响聊天、协作编辑、实时通知等功能的正常使用。本文将从技术原理、常见诱因以及系统化排查步骤三个维度，为开发者提供全面解析与解决指南。

什么是 Socket.IO 及 WebSocket 握手

Socket.IO 是一个流行的实时通信库，它在底层优先使用 WebSocket 协议，并在 WebSocket 不可用时降级为 HTTP 长轮询。当客户端（如 React 应用）发起连接时，首先会通过 HTTP 发送一个 Upgrade 请求，服务器若支持 WebSocket，则返回 101 Switching Protocols 状态码，完成握手。如果服务器返回 404，则意味着服务器无法识别或处理该握手请求。

错误发生的典型场景

在 React 浏览器环境下，该错误通常出现在以下情况：

前后端部署分离：前端 React 应用部署在静态服务器（如 Nginx、Vercel），后端 Socket.IO 服务运行在不同的端口或域名上。
路径不匹配：客户端连接地址与服务端注册的命名空间或路径不一致。
代理配置缺失：开发环境使用 webpack-dev-server 或 Vite，未正确代理 WebSocket 请求。
服务器未正确初始化：后端未正确引入或配置 Socket.IO。

根本原因分析

1. 路径冲突或缺失

Socket.IO 默认在 /socket.io/ 路径下处理握手。如果客户端使用 io("http://localhost:3001")，而服务端监听在 3001 端口且正确安装了 socket.io，一般无问题。但若后端使用 io.listen(server, { path: '/myapp' }) 自定义了路径，则客户端必须同步指定 io("http://...", { path: '/myapp' })，否则 404 出现。

2. 跨域与代理问题

在 React 开发模式下（npm start），浏览器运行在 localhost:3000，后端可能运行在 3001 端口。跨域限制下，WebSocket 握手请求被浏览器拦截或服务器拒绝。开发时常用 proxy 配置：在 package.json 中设置 "proxy": "http://localhost:3001"，但该代理仅转发普通 HTTP 请求，不处理 WebSocket 升级。正确的做法是在 Webpack 的 devServer 中增加 ws: true 或使用 sockjs 的代理规则。

3. 生产环境 Nginx 反向代理配置错误

生产环境中，通常使用 Nginx 将 /socket.io/ 路径转发给 Node.js 后端。若配置缺少 WebSocket 支持，会导致 404。示例错误配置：

location /socket.io/ {
    proxy_pass http://node_backend;
}

正确配置需增加 proxy_set_header Upgrade $http_upgrade; 和 proxy_set_header Connection "upgrade";，以及 proxy_http_version 1.1;。

4. 服务器端未启动或路由抢占

如果后端使用 Express，且在其路由中定义了 app.use('/socket.io', ...) 但未正确导出，或者存在其他中间件拦截了 /socket.io 路径，也会导致握手请求被错误匹配。

系统化排查与解决方案

步骤一：检查客户端连接地址

确保 io() 的第一个参数与后端实际地址一致。例如后端运行在 http://localhost:3001，则：

// React 客户端
import { io } from "socket.io-client";
const socket = io("http://localhost:3001");

如果后端自定义了路径，加上 path 选项：

const socket = io("http://localhost:3001", { path: "/myapp" });

步骤二：验证服务端初始化代码

Node.js 后端典型代码：

const express = require('express');
const http = require('http');
const { Server } = require('socket.io');

const app = express();
const server = http.createServer(app);
const io = new Server(server, {
    cors: { origin: "*" } // 开发时允许跨域
});

io.on('connection', (socket) => {
    console.log('Client connected');
});
server.listen(3001);

注意：必须使用 http.createServer(app) 而不是直接用 express().listen()，因为 Socket.IO 需要直接绑定到原生 HTTP 服务器。

步骤三：检查开发代理配置

使用 Vite 时，在 vite.config.js 中配置：

export default {
  server: {
    proxy: {
      '/socket.io': {
        target: 'http://localhost:3001',
        ws: true
      }
    }
  }
}

使用 Create React App 时，推荐直接使用 socket.io-client 连接后端实际地址，而非依赖代理，因为 CRA 的 proxy 默认不支持 WebSocket。

步骤四：Nginx 生产配置修正

location /socket.io/ {
    proxy_pass http://node_backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

步骤五：使用网络工具抓包确认

打开浏览器开发者工具中的 Network 标签，过滤 WS 或 404 请求，查看请求 URL 与响应头。如果看到请求路径为 /socket.io/?EIO=4&transport=polling 并返回 404，说明路径问题；若请求 wss:// 协议但返回 404，则可能是 Nginx 或服务器未开启 TLS 正确配置。

进阶考虑：端口复用与命名空间

如果后端在同一端口同时提供 REST API 和 WebSocket，建议将 Socket.IO 绑定到相同服务器实例。避免使用不同端口导致跨域复杂性。另外，使用命名空间（Namespace）可以隔离不同模块，但务必保证客户端和服务端命名空间一致。

总结

“Unexpected response code: 404”在 Socket.IO 握手阶段出现，本质是服务器未能识别客户端的升级请求。根本原因多集中在路径不一致、代理缺失或服务器初始化不当。开发者应按照“客户端→代理→服务器→响应”的链路逐层排查，尤其注意开发环境代理对 WebSocket 的特殊处理，以及生产环境 Nginx 的升级头配置。掌握这些排查思路，大部分实时通信连接问题都能迎刃而解。

随着 React 和 Node.js 生态的不断发展，Socket.IO 仍在实时应用中扮演关键角色。希望本文能帮助开发者快速定位并解决这一常见但棘手的错误，保障应用实时交互的稳定性。

Socket.IO &quot;Error during WebSocket handshake: Unexpected response code: 404&quot; in React browser