Socket.io跨域连接失败排查：同源正常跨域异常

• 检查Session Cookie的跨域传递配置
  跨域场景下withCredentials: true生效需要满足多个条件：

  1. 服务端Access-Control-Allow-Origin必须设为具体的http://localhost:8000，不能用通配符*；同时确保Access-Control-Allow-Credentials设为true。
  2. 检查服务端返回的Session Cookie的SameSite属性：如果新UI是HTTP协议的localhost:8000，而原应用是HTTPS的mylocalhostdomain.com，Cookie的SameSite不能设为None（因为None要求Secure属性，HTTP站点无法携带带Secure的Cookie），可暂时设为Lax或Strict测试；如果都是HTTPS环境，SameSite设为None并加上Secure属性。
  3. 服务端的KeyError: 'Session is disconnected'核心原因是跨域请求未携带有效Session Cookie，导致服务端无法找到对应会话，进而无法完成Socket.IO的连接初始化。

• 验证Socket.IO版本兼容性
  前端Socket.IO客户端与Python服务端（python-socketio）的版本必须严格匹配：

  • 前端v4.x ↔ python-socketio v5.x
  • 前端v3.x ↔ python-socketio v4.x
    版本不匹配会导致握手成功（返回200和sid）但后续无法建立真正的连接，从而不触发connect事件。

• 排查WebSocket升级的跨域支持
  Socket.IO默认优先使用WebSocket，跨域下需确保服务端支持WebSocket的跨域请求：

  1. 在CORS配置中允许Upgrade、Connection、Sec-WebSocket-Key、Sec-WebSocket-Version这些请求头。
  2. 查看浏览器Network面板，确认是否有WebSocket请求（ws/wss协议）。如果WebSocket连接失败，检查是否降级到轮询模式，轮询请求是否携带了正确的Session信息。

• 调整Session共享策略
  原应用的Session Cookie域名是mylocalhostdomain.com，而新UI在localhost:8000，浏览器默认不会跨域名携带Cookie。这种场景下：

  • 若要继续使用Session Cookie，需将Cookie的domain设为.mylocalhostdomain.com（仅适用于同主域的二级域名，localhost不适用）。
  • 更可靠的方案是改用无Cookie认证：在Socket.IO连接时通过query参数传递认证token，服务端验证token后获取会话，例如客户端连接配置：io('server-url', { withCredentials: true, query: { token: 'user-auth-token' } })，服务端在连接事件中解析token并绑定会话。

• 开启详细日志定位问题

  1. 服务端开启Socket.IO调试日志：python-socketio初始化时添加logger=True, engineio_logger=True，查看握手过程中Session加载的详细错误信息，明确Session is disconnected的触发时机。
  2. 客户端开启调试模式：io('server-url', { debug: true })，查看控制台输出的连接步骤，是否有隐藏的错误提示。

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