子路径下WebSocket代理失效本质是Nginx未准确传递协议升级请求，需聚焦路径精确匹配、Upgrade/Connection头透传及HTTP/1.1协议启用三环节：location必须严格匹配前端WS路径（如/chat/ws/），配置proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade和proxy_set_header Connection "upgrade"，并设proxy_read_timeout防60秒断连。
子路径下WebSocket代理转发失效，本质是Nginx未能将客户端的协议升级请求准确、完整地传递到后端服务。问题常不报错，但连接卡在握手阶段（如浏览器显示failed: Error during WebSocket handshake: Unexpected response code: 400或直接断开），排查需聚焦路径匹配、头透传和协议兼容三个关键环节。
检查location路径是否精确匹配前端发起的WS请求URL
路径不匹配是最隐蔽也最常见的原因。Nginx的location匹配是严格字符串/正则匹配，末尾斜杠影响极大：
- 若前端连接地址是
ws://example.com/chat/ws，而配置写的是location /chat { ... }，则实际匹配到的是/chat，但请求路径为/chat/ws，Nginx默认会把完整路径（含/chat/ws）拼接到proxy_pass目标后——如果后端只监听/ws，就会404 - 正确做法是显式带斜杠：用
location /chat/ws/ { proxy_pass http://backend/ws/; }，确保路径重写可控；或统一用正则匹配location ~ ^/chat/ws(/.*)?$ { ... } - 开启
access_log并查看日志中$request_uri和$upstream_http_content_type字段，确认Nginx是否真的收到了该路径的请求
验证Upgrade和Connection头是否真正透传到后端
WebSocket握手依赖两个关键请求头：Upgrade: websocket 和 Connection: Upgrade。Nginx默认会过滤掉Connection这类逐跳头：
- 必须在对应
location块中明确设置：proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection "upgrade"; - 注意：
$http_upgrade是Nginx内置变量，只在客户端请求中存在Upgrade头时才有值；若用wss（HTTPS）且SSL终止在Nginx，该变量可能为空——此时需配合map指令做兜底，例如：map $http_upgrade $connection_upgrade { default upgrade; '' close; }，再用proxy_set_header Connection $connection_upgrade; - 用
curl -i -H "Upgrade: websocket" -H "Connection: Upgrade" http://your-nginx/chat/ws手动模拟握手，观察后端是否返回101 Switching Protocols
确认后端服务是否能接收并处理代理后的路径与Host头
后端应用常根据Host、原始路径或X-Forwarded-For等头做路由或鉴权，代理后这些信息可能变化：
-
proxy_set_header Host $host;应保留，避免后端因Host不匹配拒绝请求；若后端依赖原始域名做CORS或证书校验，可改用proxy_set_header Host $http_host; - 检查后端日志，看收到的请求路径是
/chat/ws还是/ws——这取决于proxy_pass结尾是否有/。例如：proxy_pass http://backend/;会剥离/chat/ws前缀；proxy_pass http://backend;（无尾部斜杠）则会把完整路径转发过去 - 某些框架（如Spring Boot）对WebSocket路径注册敏感，需确保后端暴露的端点路径与Nginx转发后的路径一致，必要时调整后端配置或使用
rewrite重写
排除超时与连接中断干扰
子路径下若未配置长连接超时，Nginx可能在空闲1分钟后主动关闭TCP连接，导致心跳失败：
- 在对应
location中设置足够长的超时：proxy_read_timeout 86400;（24小时），proxy_send_timeout 86400; - 禁用缓冲：
proxy_buffering off;，避免Nginx缓存WebSocket帧造成延迟或粘包 - 若使用
wss，还需确认SSL配置完整（ssl_certificate、ssl_certificate_key），且Nginx监听443 ssl，否则TLS握手失败也会表现为连接拒绝
