Nginx 反向代理 WebSocket 必须加的那三行配置

一、问题现象

用 Nginx 给后端服务做反向代理时，HTTP 接口一切正常，但前端 WebSocket 一直连不上：浏览器控制台报 WebSocket connection failed，或者连接建立后立刻断开，状态码是 200 而不是 101。这类问题十有八九不是后端代码的锅，而是 Nginx 默认不会转发 WebSocket 的升级请求。

二、原因

WebSocket 建立连接时，浏览器先发一个 HTTP 请求，带上两个特殊头部：Connection: Upgrade 和 Upgrade: websocket。Nginx 默认按普通 HTTP 请求处理，既不会把这两个头部原样传给后端，也不会保持长连接，握手必然失败。

三、三行关键配置

在对应的 location 块里加上：

location /ws/ {

    proxy_pass http://backend;

    proxy_http_version 1.1;

    proxy_set_header Upgrade $http_upgrade;

    proxy_set_header Connection "upgrade";

}

严格说是三件事：proxy_http_version 1.1、Upgrade 头、Connection 头。HTTP/1.1 是前提，因为 Upgrade 机制只在 1.1 里定义；后两行把客户端的升级意图透传给后端。

四、进阶写法

如果同一个 location 既想兼容普通请求又想兼容 WebSocket，可以用 map 变量：

map $http_upgrade $connection_upgrade {

    default upgrade;

    '' close;

}

然后 proxy_set_header Connection $connection_upgrade。这样没有 Upgrade 头的普通请求不会被强加 upgrade。

五、其他注意事项

1. wss 需要在 Nginx 层终止 TLS，证书配在 server 块的 listen 443 ssl 上；

2. 长连接空闲超时默认 60 秒，必要时调大 proxy_read_timeout；

3. 改完记得 nginx -t 校验后再 reload。

总结：WebSocket 反代连不上，先检查这三行配置，多数情况下加上就通了。