WebSocket状态码详解与关闭码对照表

WebSocket关闭码1006并非服务端错误，而是客户端在TCP无声中断时自动生成的“哑巴状态码”，无日志、无原因、无法直接定位根因，需结合网络超时、代理静默断连或进程崩溃等上下文排查；真正值得警惕的是服务端主动发出的1011（服务器内部错误），它携带可读reason且必有服务端异常日志；前端应仅依赖1000、1001、1011、1013等语义明确、由对端主动发送的状态码驱动重连策略，避免被1005/1006误导；自定义码4xxx虽灵活但受限于中间件兼容性，内网直连可用，经代理则推荐用标准码1008+结构化reason——比死记数字更重要的是穿透协议表象，通过抓包看清Close Frame真实载荷。

为什么 event.code === 1006 几乎无法定位根因？

这个状态码本质是客户端兜底行为：当 TCP 连接已断、但没收到任何关闭帧（Close Frame）时，浏览器或 WebSocket 客户端库就填上 1006 并触发 onclose。它不来自服务器，也不带 event.reason。

• 网络层中断（如 NAT 超时、移动网络切换）会直接 kill TCP，无帧可发
• 负载均衡器（如 Nginx、ALB）默认 60s 空闲超时，静默断连
• 服务进程 OOM 或 panic 崩溃，来不及调用 close()
• SSL/TLS 握手失败（如证书过期）发生在 WebSocket 升级前，根本进不到协议层

1011 才是真正该盯住的服务端错误信号

和 1006 相反，1011 是服务器主动发出的关闭帧，明确表示“我出问题了”。它通常伴随可读的 event.reason，且服务端日志里必然有对应异常堆栈。

• Node.js 的 ws 库会在未捕获异常时自动返回 1011
• Spring WebSocket 中抛出未处理的 RuntimeException，会映射为 CloseStatus.SERVER_ERROR（即 1011）
• Go 的 gorilla/websocket 需手动调用 c.WriteMessage(websocket.CloseMessage, websocket.FormatCloseMessage(1011, "out of memory"))
• 注意：某些框架（如早期版本的 Socket.IO）可能把业务异常也塞进 1011，需结合 event.reason 判断是否真属底层故障

哪些状态码能被前端可靠读取并用于重连策略？

只有带明确语义、且由对端主动发送的状态码，才适合驱动前端逻辑。重点盯住这四个：

• 1000：正常关闭，不重连，清理资源即可
• 1001：对端主动离开（如服务重启、页面跳转），可延迟 1–2s 后立即重连
• 1011：服务端崩了，建议指数退避（如 1s → 2s → 4s），避免雪崩
• 1013：服务端提示“稍后重试”，说明是临时过载，比 1011 更值得等待

别依赖 1005 和 1006 做决策——它们是协议占位符，不是真实事件。

自定义状态码 4xxx 怎么安全使用？

应用层自定义必须落在 4000–4999 区间，且要确保两端都理解其含义。比如业务需要区分“账号被踢”和“权限失效”：

• 服务端发送：socket.close(4001, "kicked_by_admin")
• 前端监听：if (event.code === 4001) { showKickModal(); }
• 注意：Nginx 等中间件可能截断或忽略非标准码，4xxx 建议只用于纯内网或直连场景
• 若经代理，优先用 1008（Policy Violation）+ event.reason 传结构化 JSON，兼容性更好

真正难的从来不是记住每个数字，而是分清哪些码来自网络底层、哪些来自服务逻辑、哪些只是客户端的无奈猜测——抓包看 Close Frame 载荷，比背表管用十倍。

好了，本文到此结束，带大家了解了《WebSocket状态码详解与关闭码对照表》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！