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 分钟内定位问题。