WebSocket前后端握手失败400 WebSocket请求头Headers设置【避坑】-js教程-PHP中文网

400错误主因是websocket握手请求头在传输链路中被丢弃、篡改或校验失败；需重点检查upgrade、connection、sec-websocket-key是否合规透传，nginx须配置proxy_http_version 1.1、proxy_set_header upgrade $http_upgrade、proxy_set_header connection "upgrade"，cdn需开启websockets开关，sec-websocket-key须为24字符合法base64，origin与host头须匹配服务端白名单。

websocket前后端握手失败400 websocket请求头headers设置【避坑】

400 错误基本不是前端代码写错了，而是 WebSocket 握手请求头在传输链路中被丢弃、篡改或校验失败。重点盯住 Upgrade、Connection、Sec-WebSocket-Key 这三个头是否合规且透传到位。

为什么浏览器发的 WebSocket 请求头到了后端就没了？

Nginx 默认把 Upgrade 和 Connection 当作“逐跳头”（hop-by-hop），直接过滤不转发；同时默认用 HTTP/1.0 转发，而 WebSocket 升级必须基于 HTTP/1.1。

proxy_http_version 1.1 必须显式设置，否则后端收不到升级语义
proxy_set_header Upgrade $http_upgrade —— 用变量捕获原始值，不能硬写 "websocket"，否则多协议（如 chat, json）会挂
proxy_set_header Connection "upgrade" —— 注意是全小写 "upgrade"，写成 "Upgrade" 或 "Upgarde" 都会触发 400
如果用了 CDN（如 Cloudflare），确认后台已开启 “WebSockets” 开关，否则它根本不会把 Upgrade 头透给源站

Sec-WebSocket-Key 格式不对也会 400

这个头不是前端能随便填的，浏览器自动生成，但某些调试工具（如 Apifox、curl 手动构造）或代理中间件可能生成非法值，error_log 常见报错：invalid Sec-WebSocket-Key。

WebSocket 8.18.2

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

下载

长度必须是 24 字符（Base64 编码后的 16 字节随机数），少一位或多一位都拒收
只允许 A–Z、a–z、0–9、+、/、=，含空格、中文、下划线会直接 400
不能重复使用同一个 Key（部分严格服务端会校验历史 Key 是否已用过）
用 curl 测试时别手写 Key，推荐用 openssl rand -base64 16 生成

Sec-WebSocket-Protocol 传参要注意字符限制

这是前端唯一能“可控”塞业务参数进握手头的方式（比如 token、user_id），但它不是任意字符串都能塞。

子协议值只能含 ASCII 字母、数字、短横线 - 和点号 .，不能有 @、_、中文、空格、斜杠
前端写法：new WebSocket("wss://host/ws", ["auth-v1", "user-123"])，第二个参数是数组，值会拼成逗号分隔字符串进 Sec-WebSocket-Protocol 头
后端拿到的是完整字符串（如 auth-v1,user-123），需自行解析，不能假设只有一个值
若要传 JWT，得先 base64url 编码再过滤非法字符，否则 Nginx 或服务端中间件可能截断或报 400

Origin 和 Host 头不匹配也静默 400

很多框架（如 Spring Boot 的 WebSocketHandler、Swoole 的 onHandshake）默认校验这两个头，但错误不打日志，只默默返回 400。

Origin 必须与服务端配置的白名单完全一致（包括协议、端口、路径），http://localhost:3000 ≠ http://127.0.0.1:3000
Host 头必须匹配 Nginx 的 server_name 或后端虚拟主机配置，否则 Nginx 可能路由到默认 server，返回 400 或 444
本地开发常用 localhost，但生产环境若用 IP 直连，Origin 是 http://x.x.x.x，而白名单没加这条，就会跪
用 curl -H "Origin: https://myapp.com" wss://... 模拟时，注意 wss:// 和 Origin 协议必须一致，否则部分服务端拒绝

真正难排查的不是哪行配置漏了，而是多个环节（浏览器 → CDN → Nginx → PHP-FPM/Swoole → 应用层）各自校验一次，任何一层卡住都只回 400，且不告诉你卡在哪。最稳的做法：开 Nginx error_log ... info，抓包看实际发出的请求头，再比对后端收到的，差哪一环就查哪一环。