websocket连上即断基本是握手失败而非心跳问题，需检查network中ws响应是否为101 switching protocols及upgrade、connection响应头是否齐全，重点排查nginx是否漏配proxy_http_version 1.1、proxy_set_header upgrade $http_upgrade、proxy_set_header connection "upgrade"和proxy_read_timeout≥3600。

WebSocket连上后马上断开，**基本不是心跳没配，而是连接压根没真正建立成功**——90% 以上的情况卡在 HTTP 升级阶段（即握手失败），根本没走到心跳这一步。

检查浏览器 Network 中 WebSocket 的响应状态码和头信息

这是最快速确认是否握手失败的方法。打开 DevTools → Network → 切换到 WS 标签，点击对应连接项：

• Response Headers 必须包含 HTTP/1.1 101 Switching Protocols，否则服务端拒绝升级
• 必须有 Upgrade: websocket 和 Connection: Upgrade 两个响应头，缺一不可
• 若看到 200 OK、403 Forbidden 或 502 Bad Gateway，说明请求被拦截或服务端未启用 WebSocket 协议处理逻辑
• Chrome 有时会显示“已连接”但实际是假连接（比如 Nginx 返回了 200 + HTML 页面），此时 Frames 面板为空或报错 Failed to execute 'send' on 'WebSocket': Still in CONNECTING state

确认 Nginx 是否透传 Upgrade 请求并维持长连接

Nginx 是生产环境最常“背锅”的中间件，它默认把 WebSocket 当普通 HTTP 处理，60 秒无数据就发 RST 断连。漏配任意一项，都会导致连接秒断：

• proxy_http_version 1.1 —— 必须显式声明，HTTP/1.0 不支持 Upgrade
• proxy_set_header Upgrade $http_upgrade —— 注意变量名是 $http_upgrade，不是 $upgrade（常见拼写错误）
• proxy_set_header Connection "upgrade" —— 双引号不能少，且值必须是 "upgrade" 字面量
• proxy_read_timeout 3600 —— 建议设为 ≥3600（1 小时），远大于你的心跳间隔 ×2；设成 60 是绝大多数“连上即断”的元凶

配置生效后，用 nginx -t && nginx -s reload 重载，别只改配置不 reload。

WebSocket 8.18.2

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

下载

验证服务端是否因 Origin / Token 拒绝连接

很多框架（如 Spring WebSocket、FastAPI WebSocket）会在握手后立即校验 Origin 头或 Authorization / Sec-WebSocket-Protocol 中的 token，失败则直接 close 连接，不返回错误响应，前端只能看到 onclose { code: 4001, reason: "auth failed" }：

• 查看服务端日志，搜索关键词：origin mismatch、invalid token、handshake failed
• 临时关闭 Origin 校验（仅测试环境），或用 curl 手动模拟握手：
  

  curl -i -N \
    -H "Connection: Upgrade" \
    -H "Upgrade: websocket" \
    -H "Sec-WebSocket-Version: 13" \
    -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
    -H "Origin: https://your-app.com" \
    https://your-api.com/ws

• 观察响应是否含 101 和 Sec-WebSocket-Accept；若返回 403 或空响应，就是服务端策略拦截

排查客户端事件绑定时机与 URL 协议一致性

看似简单，但极易被忽略：

• 确保页面协议与 WebSocket URL 协议严格一致：https:// 页面必须用 wss://，http:// 页面只能用 ws://；混用会触发浏览器静默中断
• WebSocket 实例创建后，onopen/onerror/onclose 必须立刻绑定，不能延迟到异步回调里（例如 Promise resolve 后才绑）——否则连接已建立又关闭，事件来不及捕获
• 本地开发用 localhost 时，确认服务端监听的是 0.0.0.0:port 而非 127.0.0.1:port，否则某些系统防火墙或 Docker 网络会拦截
• 移动端 WebView 或 Electron 场景下，检查是否启用了 webSecurity: false 或自定义 session，可能影响 Origin 头行为

真正棘手的点往往藏在“看起来不该出问题”的地方：Nginx 配置里一个空格、服务端日志里一行被滚动刷走的校验失败记录、或是前端 new WebSocket() 后那毫秒级的事件绑定延迟。