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

这篇是工程型排障清单：遇到 WS 连不上时按这个顺序查，基本能定位到问题点。

先给结论

WebSocket 不通，99% 不是“框架坏了”，而是以下三类问题：

1. 路径错了 / 被路由接管
2. Upgrade 头没传进去
3. 权限或跨域拦截

一、排查顺序（强烈建议按这个来）

1. 确认访问路径是否命中后端
2. 确认 Nginx 是否走了 WebSocket location
3. 确认 Upgrade/Connection 头是否正确
4. 确认后端握手是否返回 101
5. 确认权限/登录态是否带上

二、最稳的 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/...，必须有专用 location：

location /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 传 token

5) 后端返回 404/500

如果后端直接 404，说明路径没命中。
如果后端 500，多半是拦截器/权限校验失败。

6) http 与 https 混用

主站是 https 时，WebSocket 必须用wss://，
否则浏览器会直接拦截。

四、快速自检命令

curl-i-N\-H"Connection: Upgrade"\-H"Upgrade: websocket"\"http://127.0.0.1:8123/ws/app/edit"

看到101 Switching Protocols才算后端 OK。

最后总结

排 WebSocket 先别猜，按“路径 → 头 → 状态码”三步走，
基本能在 5 分钟内定位问题。