Egg.js 集成 Socket.io 报 400 Session ID unknown 问题解决指南

在 Egg.js 项目中集成 egg-socket.io 实现长连接功能时，不少开发者会遇到一个典型环境差异问题： 本地开发环境可正常连接 WebSocket，部署到服务器正式环境后却连接失败，控制台提示 Session ID unknown ，同时伴随 HTTP 400 错误 。本文将深入剖析问题根源，提供完整解决方案，并补充相关技术原理与注意事项，帮助开发者彻底解决该问题。

一、问题现象复现

• 本地环境：使用 egg-bin dev 启动项目，WebSocket 连接正常，消息收发无异常；
• 正式环境：使用 egg-scripts start 启动项目，客户端发起 WebSocket 连接请求后，服务器返回 400 Bad Request，响应信息中包含 Session ID unknown ，连接建立失败。

二、问题核心根源剖析

该问题的本质是 Egg.js 集群启动模式与 Socket.io 协议实现的兼容性问题 ，核心矛盾在于 多进程集群 与 Socket.io 粘性会话（Sticky Session） 的依赖关系，具体可从两个层面拆解：

1. Egg.js 默认启动模式：Cluster 集群模式

Egg.js 框架为提升服务并发能力，默认采用 Cluster 模式启动（即多进程模式）。在该模式下，主进程（Master）会根据服务器 CPU 核心数 fork 出多个工作进程（Worker），并负责请求的负载均衡分发。 需要注意的是，本地开发时使用的 egg-bin dev 命令，为了简化开发流程，会对集群模式进行特殊优化（例如默认单进程启动或自动处理进程间通信），这也是本地环境能正常连接的关键原因；而正式环境使用的 egg-scripts start 命令则会严格遵循生产环境配置，默认以标准 Cluster 多进程模式启动，未开启特殊兼容处理。

2. Socket.io 协议的核心依赖：粘性会话（Sticky Session）

Socket.io 的连接建立过程分为两个阶段：

1. 握手阶段：客户端先通过 HTTP 发起握手请求，服务器验证通过后返回 Session ID 等连接信息；
2. 升级阶段：客户端携带 Session ID 再次发起请求，将 HTTP 连接升级为 WebSocket 长连接。

由于 Socket.io 的设计特性， 同一客户端的握手请求与升级请求必须路由到同一台 Worker 进程 ，否则后续升级请求携带的 Session ID 无法被正确识别（其他进程未存储该 Session 的上下文信息），从而触发 Session ID unknown 错误和 400 响应。这种 确保同一客户端请求始终路由到同一进程 的机制，就是 粘性会话（Sticky Session） 。 在 Egg.js 标准 Cluster 模式下，默认的负载均衡策略是 轮询分发 ，无法保证同一客户端的两次请求路由到同一进程，因此直接导致 Socket.io 连接失败。

三、解决方案：开启 Sticky 模式

解决问题的核心是为 Egg.js 启动进程开启 Sticky 模式，让主进程在分发请求时，通过客户端 IP 等信息做哈希计算，确保同一客户端的所有请求都路由到同一 Worker 进程，从而满足 Socket.io 对粘性会话的要求。 具体操作是修改项目根目录下的 package.json 文件，在 scripts 脚本中为启动命令添加 --sticky 参数，强制开启 Sticky 模式。

1. 修改 package.json 脚本

{
  "name": "your-egg-project",
  "version": "1.0.0",
  "scripts": {
    "dev": "egg-bin dev --sticky",  // 本地开发环境开启 Sticky 模式（与生产环境保持一致，避免环境差异）
    "start": "egg-scripts start --sticky",  // 正式环境开启 Sticky 模式
    "stop": "egg-scripts stop",  // 补充停止命令，完整生产环境脚本
    "test": "egg-bin test"  // 补充测试命令，完善脚本规范
  }
}

2. 重启项目验证

• 本地开发环境：执行 npm run dev ，重启项目后验证 WebSocket 连接正常；
• 正式环境：先执行 npm run stop 停止原有进程，再执行 npm run start 启动新进程，部署完成后验证 WebSocket 连接成功， Session ID unknown 错误消失。

四、补充说明与注意事项

1. Sticky 模式的工作原理

当开启 --sticky 参数后，Egg.js 主进程会采用 IP 哈希路由策略 ：对客户端 IP 地址进行哈希计算，根据计算结果将请求分发到固定的 Worker 进程。这种策略能确保同一客户端的所有请求（包括 Socket.io 的握手和升级请求）始终路由到同一进程，从而保障 Session 上下文的一致性。

2. 单进程模式与多进程模式的区别

如果开发者为了快速排查问题，将 Egg.js 改为单进程模式（例如执行 egg-scripts start --workers=1 ），也能解决该问题，但不推荐在生产环境使用。原因是单进程模式无法利用多核 CPU 资源，并发能力大幅下降，无法应对高流量场景；而开启 Sticky 模式的多进程集群，既能满足 Socket.io 的需求，又能充分利用服务器资源，是生产环境的最优解。

3. 其他可能导致 400 错误的场景

除了 未开启 Sticky 模式 这一核心原因外，以下场景也可能导致 Socket.io 连接 400 错误，需额外排查：

• 跨域配置问题：如果客户端与服务器存在跨域，未正确配置 egg-socket.io 的跨域参数（如 allowOrigin ），会导致握手失败；
• Session 配置不一致：本地与生产环境的 Session 存储方式（如内存、Redis）不一致，导致生产环境无法识别本地生成的 Session ID；
• 端口或代理问题：服务器端口未对外开放、存在反向代理（如 Nginx）且未正确配置 WebSocket 转发，也可能导致连接失败。

4. Nginx 反向代理场景的补充配置

如果生产环境使用 Nginx 作为反向代理，除了开启 Egg.js 的 Sticky 模式外，还需在 Nginx 配置中添加 WebSocket 转发支持，避免代理层阻断连接。示例配置如下：

server {
  listen 80;
  server_name your-domain.com;

  location / {
    proxy_pass http://127.0.0.1:7001 ;  # 指向 Egg.js 服务端口
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;  # 允许升级为 WebSocket
    proxy_set_header Connection "upgrade";  # 标记连接为升级连接
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_cache_bypass $http_upgrade;  # 升级请求不缓存
  }
}

五、总结

Egg.js 集成 Socket.io 报 Session ID unknown 400 错误的核心原因，是 Egg.js 生产环境默认的 Cluster 多进程模式未开启 Sticky 粘性会话，导致 Socket.io 握手与升级请求路由到不同进程。通过在 package.json 的启动脚本中添加 --sticky 参数，即可强制开启粘性会话，解决连接问题。 建议开发者在项目初期就将本地开发环境与生产环境的启动脚本统一配置 --sticky 参数，避免因环境差异导致线上问题；同时，在生产环境使用反向代理时，需同步配置 WebSocket 转发规则，确保长连接正常工作。