WebSocket 握手阶段中自定义 HTTP 请求头的添加方法-H5教程-PHP中文网

浏览器原生websocket不支持自定义请求头，仅能在握手阶段通过url参数、sec-websocket-protocol或首次消息传递鉴权信息；非浏览器环境（如node.js、python）则可通过客户端库直接设置headers。

websocket 握手阶段中自定义 http 请求头的添加方法

WebSocket 握手阶段本质上是一次 HTTP GET 请求，只有在这个阶段才能添加自定义 HTTP 请求头。但能否成功添加，取决于你使用的客户端环境和技术栈——浏览器原生 WebSocket 构造函数**不支持**任何自定义 header，这是由浏览器安全策略强制限制的；而服务端、Node.js、Python、Unity 或 Java 等非浏览器环境则普遍支持。

浏览器环境：无法直接设 header，需用替代方案

标准 new WebSocket(url) 会自动发送握手请求，但只允许以下字段（其余被静默丢弃）：

Sec-WebSocket-Key（自动生成）
Sec-WebSocket-Version
Connection: Upgrade
Upgrade: websocket
Origin（可读，不可写）

因此，若必须传递认证或元数据，可用以下方式替代：

WebSocket 8.18.2

WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。

下载

URL 查询参数：把 token、user_id 等编码进 ws/wss 地址，如 wss://api.example.com/chat?token=abc123&uid=1001
Sec-WebSocket-Protocol：该字段是 RFC 允许的，可用于传简单标识，如 new WebSocket(url, ["auth-v1", "json"])，服务端可从中提取协议名作鉴权依据
首次消息认证：连接建立后立即 send() 一条 JSON 认证消息，例如 {"type":"auth","token":"..."}，服务端在收到该消息前暂不处理其他数据

非浏览器环境：可直接设置 handshake headers

在 Node.js、Python、Java、Unity、.NET 等环境中，WebSocket 客户端库通常暴露底层 HTTP 请求控制能力，允许你在握手请求中自由添加 header：

Python（websockets 库）：使用 extra_headers 参数，如 connect(url, extra_headers={"Authorization": "Bearer xyz"})
Node.js（ws 库）：通过 headers 选项，如 new WebSocket(url, { headers: { "X-App-Version": "2.1.0", "Authorization": "Bearer ..." } })
Java（Spring Boot）：客户端可用 StandardWebSocketClient 配合自定义 HandshakeRequest；服务端通过 ServerEndpointConfig.Configurator#modifyHandshake 读取 header
Unity（UnityEngine.Networking 或第三方库）：部分封装库（如 BestHTTP）支持 Websocket.RequestHeaders 属性，可直接赋值字典
RestSharp（.NET）：虽非专为 WebSocket 设计，但可通过构造 RestRequest 并手动设置 AddHeader() 模拟握手请求，再交由底层 socket 处理

服务端如何读取这些自定义 header

服务端必须在 HTTP 升级（upgrade）事件中解析请求头，而非 WebSocket 数据帧阶段：

Node.js（ws）：监听 server.on('upgrade', (req, socket, head) => { console.log(req.headers['authorization']); ... })
Python（FastAPI + websockets）：在 connect handler 中访问 scope["headers"]（ASGI 环境）
Java（Spring WebSocket）：通过 HandshakeRequest.getHeaders() 获取，前提是客户端已正确发送
Nginx / 反向代理注意项：默认会过滤掉非标准 header（如 Authorization），需显式配置 proxy_pass_request_headers on; 和 proxy_set_header Authorization $http_authorization;