error_log 主要记录 websocket 握手阶段问题，不记录数据帧内容；它能捕获 upgrade 头缺失、http 版本错误、101 响应失败、header 过大及代理配置遗漏等握手异常，但数据帧异常需依赖后端日志、tcp 抓包和连接指标排查。
error_log 在分析 WebSocket 数据帧异常时作用有限，它主要记录握手阶段和连接建立过程中的问题，不记录已建立连接后的数据帧内容。
error_log 能捕获的 WebSocket 相关异常
WebSocket 协议分为两个阶段：HTTP 握手（Upgrade 请求）和后续二进制/文本数据帧传输。Nginx 的 error_log 仅深度介入第一阶段：
-
握手失败原因：如缺失
Upgrade: websocket或Connection: upgrade头、HTTP 版本降级为 1.0、上游未返回 101 状态码等，debug 级别日志会明确打印头透传过程和协议协商细节； - 连接建立中断：如 upstream refused、connection reset、timeout（proxy_read_timeout 触发）、header too large 等，对应日志中会出现 “upstream sent no valid HTTP/1.0 header” 或 “client sent invalid upgrade header”；
-
代理配置错误：例如未启用
proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade遗漏或拼写错误，debug 日志会显示 “discarding header 'Upgrade'” 等提示。
为什么 error_log 看不到数据帧内容
Nginx 对 WebSocket 的支持本质是“隧道模式”（tunnel mode）：一旦成功完成 101 响应，Nginx 就不再解析或记录后续 TCP 层的数据帧，而是将原始字节流透明转发。这意味着：
- 客户端发送的 ping/pong、text/binary 帧不会被解析或记入 error_log；
- 后端服务主动关闭连接、帧格式错误、payload 解析失败等问题，均由后端自身日志记录，Nginx 仅可能记录最终的连接断开事件（如 “recv() failed (104: Connection reset by peer)”），但无法说明是哪一帧触发；
- 即使开启 debug 级别，Nginx 也不会 dump 数据帧 payload，其 debug 日志聚焦于 HTTP 头、状态码、连接生命周期管理。
排查数据帧异常的正确路径
若遇到消息丢失、解码失败、连接静默断开等典型数据帧问题，应转向以下手段：
-
后端服务日志：检查应用层（如 Node.js ws 库、Swoole、Spring Boot WebSocket）是否抛出
InvalidFrameException、PayloadTooLargeError或超时关闭记录； - TCP 抓包分析：用 tcpdump 或 Wireshark 捕获流量，过滤 WebSocket 流（端口 + FIN/SYN 标志），观察 FIN 包发起方、RST 出现时机、是否有连续 ping 未响应；
-
Nginx 连接级指标：结合 access_log 中的
$upstream_response_time和$status，识别是否大量连接在建立后短时间内异常终止（如 status=499 或无日志）； -
操作系统连接状态：用
ss -tni查看 ESTABLISHED 连接的重传次数（retrans）、丢包（loss）、RTT 波动，判断是否为网络层问题而非协议层异常。
可辅助定位数据帧问题的 error_log 线索
虽然不记录帧内容，但某些 error_log 条目能间接指向数据帧异常根源：
-
recv() failed (104: Connection reset by peer)：常表示后端进程崩溃或主动 kill 连接，需查后端 crash 日志； -
upstream timed out (110: Connection timed out) while reading response header：说明握手卡住，不是数据帧问题，但易被误判； -
client intended to send too large chunked body：虽属 HTTP 范畴，但若前端误用分块编码发大数据，可能干扰 WebSocket 连接稳定性； - 高频出现
shutdown() failed (107: Transport endpoint is not connected)：提示连接已断但仍尝试写入，多见于后端未正确处理 close 通知。
