Socket.io服务端无法接收客户端通过extraHeaders发送的自定义请求头

问题原因分析 #

你指定了transports: ["websocket"]直接使用WebSocket传输，此时extraHeaders会被附加到WebSocket的HTTP升级请求中，但可能因为版本兼容、代理拦截或头格式问题导致服务端无法读取。另外，HTTP请求头在传输过程中会被转为小写，服务端需要用小写键名读取。

解决方案 #

1. 确保客户端与服务端Socket.IO版本一致 #

Socket.IO不同大版本（如2.x、3.x、4.x）的API存在差异，extraHeaders的处理逻辑也可能不同。请检查两端版本并保持一致，建议使用最新稳定版。

2. 修正服务端读取头的方式 #

HTTP请求头在传输时会被转为全小写，服务端需要用小写键名读取：

// 服务端代码示例
const io = require('socket.io')(server);
io.on('connection', (socket) => {
  // 读取自定义头（注意键名是小写）
  const buildNumber = socket.handshake.headers.build_number;
  console.log('build_number:', buildNumber);
  
  // 或者查看所有请求头，确认是否存在
  console.log('所有握手请求头:', socket.handshake.headers);
});

3. 尝试移除强制WebSocket传输的配置 #

如果业务允许，先移除transports: ["websocket"]，让Socket.IO默认先通过HTTP长轮询完成握手，再升级到WebSocket。此时extraHeaders会被附加到初始握手请求中，服务端更容易读取：

const socket = socketIO('wss://domain.com', {
  extraHeaders: {
    build_number: "227"
  }
});

4. 为自定义头添加X-前缀（适配部分代理/服务器） #

部分代理或服务器会过滤非标准HTTP头，将自定义头改为带X-前缀的格式：

// 客户端修改
const socket = socketIO('wss://domain.com', {
  transports: ["websocket"],
  extraHeaders: {
    "X-Build-Number": "227"
  }
});

// 服务端读取（键名转为小写）
const buildNumber = socket.handshake.headers['x-build-number'];

5. 检查代理/CDN的头传递配置 #

如果客户端与服务端之间存在Nginx、Cloudflare等代理，需要配置代理允许传递自定义头。例如Nginx需添加：

location / {
  proxy_pass http://your-backend;
  # 传递自定义头
  proxy_set_header X-Build-Number $http_x_build_number;
  proxy_set_header build_number $http_build_number;
  # 其他必要的代理配置
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
}

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