React项目socket.io-client连接报xhr poll error错误如何解决？

错误产生原因 #

• 协议版本不匹配：socket.io-client v4.x 要求服务端 Socket.IO 版本为 v3.x 及以上，版本跨度过大时握手请求失败，默认先走的HTTP长轮询请求直接报错。
• 服务端可用性异常：目标端口3001无Socket.IO服务运行、端口被占用、防火墙/安全软件拦截了端口请求，都会导致长轮询请求无法送达。
• 跨域配置错误：前端访问地址与服务端地址的端口、协议、域名不一致时，服务端未配置CORS允许规则，浏览器会直接拦截长轮询的XHR请求。
• 传输规则不兼容：Socket.IO 默认优先走HTTP长轮询再升级为WebSocket，如果服务端/反向代理（Nginx等）未允许长轮询请求，会直接抛出轮询错误。
• 本地网络限制：本地开启的代理工具、浏览器广告拦截/请求拦截插件，可能会误拦截Socket.IO的轮询请求。

排查步骤 #

• 打开浏览器控制台Network面板，过滤Fetch/XHR请求，找到路径包含/socket.io/?EIO=的请求，查看状态码：404代表服务未启动/路径错误，403代表CORS/权限拦截，5xx代表服务端内部错误。
• 在connect_error回调中打印完整错误信息：console.log('错误详情', e.message, e.code)，获取更明确的错误提示。
• 确认服务端Socket.IO版本：在服务端项目执行npm list socket.io，检查大版本是否与客户端v4.x匹配。
• 临时修改客户端传输配置，测试是否为长轮询的问题：初始化时新增transports: ['websocket']配置，强制走WebSocket协议，看是否仍报错。

修复方案 #

1. 版本匹配修复
   必须保证客户端与服务端Socket.IO大版本一致，如果服务端版本为v2.x，要么将服务端升级到v4.x，要么将客户端版本降级为"socket.io-client": "^2.5.0"。
2. 跨域规则修复
   在服务端Socket.IO初始化时添加CORS配置，Node.js服务端示例：

const { Server } = require("socket.io");
const io = new Server(3001, {
  cors: {
    origin: "http://localhost:3000", // 替换为前端实际访问地址
    credentials: true
  }
});

3. 传输规则修复
   确认服务端支持WebSocket的情况下，可以在客户端初始化时指定传输顺序，优先走WebSocket避免长轮询问题：

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

const ENDPOINT = "http://localhost:3001";

const socket = io(ENDPOINT, {
  transports: ['websocket', 'polling']
});

socket.on("connect_error", (e) => {
   console.log(e.message, e.code);
});

4. 服务可用性修复
   确认Socket.IO服务正常在3001端口启动，无端口占用，关闭本地代理工具、请求拦截插件后重试。

内容的提问来源于stack exchange，提问作者Vladimir Vladimirov