Nginx 中怎么通过 nginx.conf 配置代理服务支持 WebSocket 握手-Nginx-PHP中文网

必须配置proxy_http_version 1.1、proxy_set_header upgrade $http_upgrade、proxy_set_header connection "upgrade"三项协议升级指令，并设proxy_read_timeout和proxy_send_timeout为86400、proxy_buffering off、tcp_nodelay on，才能完成websocket握手并维持长连接。

nginx 中怎么通过 nginx.conf 配置代理服务支持 websocket 握手

要让 Nginx 通过 nginx.conf 正确代理 WebSocket 并完成握手，关键不是“开启支持”，而是**显式透传升级信号、禁用短连接默认行为、匹配长连接生命周期**。漏掉任意一项，浏览器发的是 Upgrade: websocket，后端收到的却是普通 HTTP 请求，返回 200 而非 101，握手直接失败。

必须写全的三项协议升级配置

WebSocket 握手本质是一次带特定头的 HTTP/1.1 请求，Nginx 默认不处理也不转发这些字段，必须手动补全：

proxy_http_version 1.1;：强制使用 HTTP/1.1，HTTP/1.0 不支持 Upgrade 机制，设成 1.0 或不写都会导致握手中断
proxy_set_header Upgrade $http_upgrade;：用变量传递，不能硬写 "websocket"；某些客户端（如 IoT 设备）可能发 "mqtt" 或 "chat"，硬编码会截断协议协商
proxy_set_header Connection "upgrade";：注意是带英文双引号的字符串 "upgrade"，不是 $http_connection 或 $connection_upgrade；Connection 是逐跳头，不可继承，Nginx 必须主动设为 upgrade 才能触发后端协议切换

超时参数必须调大，否则连接静默断开

WebSocket 是长连接，Nginx 默认的 proxy_read_timeout 60 会让空闲 60 秒的连接被单方面关闭，客户端无错误提示，只看到“突然断开”：

Nginx Config Linter

对 Nginx 配置文件进行语法检查、验证和安全、性能审计。

下载

proxy_read_timeout 86400;：建议设为 24 小时（86400 秒），适用于聊天、监控等允许长时间静默的场景
proxy_send_timeout 86400;：防止后端分片发送大消息或延迟响应 ping/pong 时被中途切断
不用调 keepalive_timeout：它只影响 HTTP 短连接复用，对 WebSocket 无效

location 块中还需补充的关键项

除核心三项外，以下配置能避免常见干扰：

proxy_buffering off;：禁用缓冲，避免 WebSocket 帧被缓存合并或延迟转发
tcp_nodelay on;：禁用 Nagle 算法，减少小包传输延迟，提升实时性
proxy_set_header Host $host;：确保后端能正确识别原始域名，尤其涉及多租户或虚拟主机时
若代理 WSS（wss://），SSL 终止需在 Nginx 完成，且确认 CDN 或负载均衡器未剥离 Upgrade 和 Connection 头

附：最小可用 location 示例

将以下配置放入 server 块内对应路径（如 /ws/ 或 /）：

location /ws/ {
    proxy_pass http://backend_ws;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400;
    proxy_send_timeout 86400;
    proxy_buffering off;
    tcp_nodelay on;
}

配置完成后 reload Nginx（nginx -s reload），再用浏览器开发者工具 Network 标签页确认 WebSocket 请求状态码是否为 101 Switching Protocols —— 这才是握手成功的唯一标志。