Nginx代理WebSocket需配置HTTP/1.1升级、透传Upgrade头、设置长超时（如3600秒）、关闭缓冲，并精准匹配/ws等路径，否则会导致连接中断、光标不同步等问题。

用 Nginx 代理 WebSocket 是在线协作编辑器（如多人实时编辑文档）的关键一环。它本身不处理业务逻辑，但必须正确透传连接、维持长连接、避免超时中断，否则会出现“突然断连”“光标不同步”“操作丢失”等问题。

WebSocket 连接需显式升级

Nginx 默认把所有请求当 HTTP 处理，而 WebSocket 建立依赖 HTTP 升级协议（Upgrade: websocket）。若不配置，Nginx 会直接返回 400 或 502，前端收不到 101 Switching Protocols 响应，连接失败。

必须在 location 块中添加以下头信息：

• proxy_http_version 1.1; —— 启用 HTTP/1.1，支持 Upgrade 头
• proxy_set_header Upgrade $http_upgrade; —— 透传 Upgrade 请求头
• proxy_set_header Connection "upgrade"; —— 显式声明连接升级，不能写成 ’Upgrade’ 或省略引号

防止连接被意外关闭

默认情况下，Nginx 的 proxy_read_timeout 和 proxy_send_timeout 都是 60 秒。WebSocket 是长连接，空闲时无数据收发，超时后 Nginx 会主动断开，导致前端重连、状态丢失。

建议设为较大值（如 1 小时），或根据业务容忍度调整：

• proxy_read_timeout 3600; —— 等待后端响应的最大时间
• proxy_send_timeout 3600; —— 向后端发送请求的最大等待时间
• proxy_buffering off; —— 关闭缓冲，避免延迟转发消息（协作场景对实时性敏感）

匹配路径与后端服务对齐

协作编辑器通常将 WebSocket 路径设计为 /ws?docId=xxx 或 /api/v1/editor/ws。Nginx 的 location 必须能准确捕获这些路径，且注意是否带查询参数。

推荐写法（兼容带参和无参）：

• location ^~ /ws { —— 前缀匹配，高效且避免正则干扰
• proxy_pass http://backend_ws; —— 后端需支持同路径，不要自动改写 URI（除非明确需要）
• 如需保留 query string，确保不加 / 结尾或使用 rewrite 显式传递

验证与常见问题定位

配置完别急着上线，先做三件事：

• 用 curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" http://your-domain/ws 检查是否返回 101
• 浏览器开发者工具 Network 标签中查看 WS 连接的 Status 是否为 101，而非 200/502
• 后端日志确认 upgrade 成功、连接未被 Nginx 中断（搜索 “client closed connection” 或 “upstream prematurely closed”）