Nginx 反代与 WebSocket 常见坑排查清单

这篇是工程型排障清单遇到 WS 连不上时按这个顺序查基本能定位到问题点。先给结论WebSocket 不通99% 不是“框架坏了”而是以下三类问题路径错了 / 被路由接管Upgrade 头没传进去权限或跨域拦截一、排查顺序强烈建议按这个来确认访问路径是否命中后端确认 Nginx 是否走了 WebSocket location确认 Upgrade/Connection 头是否正确确认后端握手是否返回 101确认权限/登录态是否带上二、最稳的 Nginx WebSocket 配置模板map $http_upgrade $connection_upgrade { default upgrade; close; } location /ws/ { proxy_pass http://127.0.0.1:8123/ws/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_read_timeout 3600s; proxy_send_timeout 3600s; proxy_buffering off; }三、最常见的 6 个坑1) location 被 /api/ 抢走如果 WebSocket 路径是/api/ws/...必须有专用 locationlocation /api/ws/ { ... }并且放在/api/前面。2) proxy_pass 路径写错location /api/ws/ { proxy_pass http://127.0.0.1:8123/ws/; }上面会把/api/ws/xxx改成/ws/xxx后端 404。正确写法proxy_pass http://127.0.0.1:8123;3) 没有 Upgrade 头没有这两行基本没戏proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade;4) Cookie / Token 没带WebSocket 也是握手 HTTP如果依赖登录态要保证 Cookie 能带上或直接 query 传 token5) 后端返回 404/500如果后端直接 404说明路径没命中。如果后端 500多半是拦截器/权限校验失败。6) http 与 https 混用主站是 https 时WebSocket 必须用wss://否则浏览器会直接拦截。四、快速自检命令curl-i-N\-HConnection: Upgrade\-HUpgrade: websocket\http://127.0.0.1:8123/ws/app/edit看到101 Switching Protocols才算后端 OK。最后总结排 WebSocket 先别猜按“路径 → 头 → 状态码”三步走基本能在 5 分钟内定位问题。