WebSocket连接后立即断开排查与解决方法

WebSocket连接后立即断开，绝大多数情况并非心跳机制缺失，而是HTTP升级握手阶段就已失败——根本没进入通信环节；关键要通过浏览器Network面板确认响应是否为101状态码及完整的Upgrade/Connection响应头，并重点排查Nginx配置中proxy_http_version、Upgrade/Connection头透传、proxy_read_timeout等四项易漏项，同时兼顾服务端Origin或Token校验拦截、客户端协议一致性与事件绑定时机等隐蔽陷阱，真正的问题往往藏在看似微小的配置空格、变量拼写或毫秒级时序偏差之中。

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。

验证服务端是否因 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() 后那毫秒级的事件绑定延迟。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~