浏览器原生WebSocket不支持自定义请求头，仅能在握手阶段通过URL参数、Sec-WebSocket-Protocol或首次消息传递鉴权信息；非浏览器环境（如Node.js、Python）则可通过客户端库直接设置headers。
WebSocket 握手阶段本质上是一次 HTTP GET 请求，只有在这个阶段才能添加自定义 HTTP 请求头。但能否成功添加，取决于你使用的客户端环境和技术栈——浏览器原生 WebSocket 构造函数**不支持**任何自定义 header，这是由浏览器安全策略强制限制的；而服务端、Node.js、Python、Unity 或 Java 等非浏览器环境则普遍支持。
浏览器环境：无法直接设 header，需用替代方案
标准 new WebSocket(url) 会自动发送握手请求，但只允许以下字段（其余被静默丢弃）：
-
Sec-WebSocket-Key（自动生成） Sec-WebSocket-VersionConnection: UpgradeUpgrade: 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）：在
connecthandler 中访问scope["headers"]（ASGI 环境） -
Java（Spring WebSocket）：通过
HandshakeRequest.getHeaders()获取，前提是客户端已正确发送 -
Nginx / 反向代理注意项：默认会过滤掉非标准 header（如
Authorization），需显式配置proxy_pass_request_headers on;和proxy_set_header Authorization $http_authorization;
安全与兼容性提醒
即使技术上可行，也要注意：
- 敏感信息（如 token）避免放在 URL 中，易被日志、代理、CDN 缓存泄露
- 某些旧版 Android WebView 或特定浏览器内核对
Sec-WebSocket-Protocol解析不一致，慎用于关键鉴权 - 若使用反向代理（如 Nginx、Cloudflare），确认其未 strip 或重写自定义 header
- 服务端务必校验 header 存在性与格式，拒绝无认证头的握手请求，防止未授权接入
