HTML5WebSocket连接不上_HTML5实时通信连接失败排查教程【说明】

websocket连接失败主因是协议/域名/端口不匹配、https页面连ws被拒、代理未透传升级头或防火墙拦截；chrome network需切ws标签查看；node.js ws库须json.stringify发送对象，socket.io需检查路径、跨域及代理配置。

WebSocket onerror 触发但没具体错误信息

浏览器里 WebSocket 实例一创建就进 onerror，控制台却只显示“WebSocket connection to ‘ws://…’ failed”，没有更细的错误码或原因——这说明连接根本没发出去，或者被拦截在了网络层以下。

常见原因不是代码写错了，而是协议、域名、端口不匹配：

• 前端用 ws:// 但服务端只监听 wss://（或反过来），尤其本地开发时容易混用；
• 页面是 https:// 开的，但尝试连 ws://（非加密），现代浏览器直接拒绝，必须改用 wss://；
• 代理或 nginx 没透传 WebSocket 升级头，Connection: Upgrade 和 Upgrade: websocket 被丢弃或改写；
• 防火墙或公司网络策略屏蔽了目标端口（比如非 80/443 的自定义端口）。

Chrome 控制台 Network 面板看不到 WebSocket 连接

这不是 bug，是 Chrome 的设计：WebSocket 连接不会出现在 Network 主列表里，得手动点左侧边栏的 WS 标签页才能看到。如果没这个标签，说明连接压根没建立成功，或者被降级成了轮询（比如用了 Socket.IO 且配置了 fallback）。

验证是否真连上了，比看面板更靠谱的方式是：

立即学习“前端免费学习笔记（深入）”；

• 在 onopen 回调里打个 console.log('connected')；
• 检查 socket.readyState：0 = CONNECTING，1 = OPEN，2 = CLOSING，3 = CLOSED；
• 用命令行工具直连测试：curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" http://localhost:3000/ws（注意返回里要有 101 Switching Protocols）。

Node.js 后端用 ws 库但客户端收不到 message

典型现象：连接状态是 OPEN，服务端调了 ws.send()，但前端 onmessage 不触发。大概率是数据格式或发送时机问题。

ws 库默认只接受字符串或 Buffer，不能直接发对象：

• ❌ 错误：ws.send({ type: 'ping' }) → 会静默失败或抛错；
• ✅ 正确：ws.send(JSON.stringify({ type: 'ping' }))；
• 如果发二进制，确保前端用 socket.binaryType = 'arraybuffer' 并正确解析；
• 还要确认服务端没在 ws.on('connection', ...) 外部提前调 ws.send()——实例还没完全 ready 就发，会被丢弃。

Socket.IO 连不上，但原生 WebSocket 可以

说明问题不在网络通路，而在 Socket.IO 自身握手流程。它不是裸 WebSocket，而是先 HTTP 轮询建立 session，再升级。

最常踩的坑是路径和跨域配置不一致：

• 前端 new io('http://localhost:3000', { path: '/my-socket' })，后端却没配 server.listen(3000, { path: '/my-socket' })；
• 前端域名是 https://app.example.com，后端 cors 没放开该域名，或没设 credentials: true；
• 反向代理（如 Nginx）没转发 /socket.io/ 路径，或漏掉了 proxy_http_version 1.1 和 proxy_set_header Upgrade $http_upgrade 这两行。

Socket.IO 的调试开关很关键：localStorage.debug = 'socket.io-client:*，然后刷新页面看 console 里握手每一步卡在哪。