在 nginx 中代理超时导致前端连接中断，通常是因为默认的连接等待时间过短，或者后端服务处理请求耗时超过了 nginx 的阈值。解决这个问题的核心做法是调整 nginx 配置文件中与 `proxy_pass` 相关的三个关键超时参数：`proxy_connect_timeout`、`proxy_send_timeout` 和 `proxy_read_timeout`。通过将这些值设置为大于后端实际处理时间的数值，可以防止 nginx 主动切断长连接或慢查询的请求。如果涉及 websocket 等需要保持长连接的协议，还需要额外设置 http 升级头的相关超时参数。
如何区分三种代理超时的作用范围
Nginx 的代理超时机制分为三个阶段，分别对应建立连接、发送请求和读取响应。理解它们的区别有助于精准定位超时发生的环节。`proxy_connect_timeout` 控制的是 Nginx 与后端服务器（如 Node.js、Java 或 Python 应用）建立 TCP 连接的时间。如果后端服务启动缓慢或网络延迟高，这个值过小会导致连接失败。`proxy_send_timeout` 则是 Nginx 向后端发送完整请求体（Request Body）的超时时间。对于上传大文件或提交复杂表单的场景，如果发送速度较慢，可能会触发此超时。`proxy_read_timeout` 是最常见的超时原因，它定义了 Nginx 从后端服务器读取响应数据（Response）的间隔时间。如果后端业务逻辑复杂，执行时间长，Nginx 会认为后端无响应而断开连接，向前端返回 504 Gateway Time-out 错误。
server {
listen 80;
server_name example.com;
location /api/ {
proxy_pass http://backend_server;
# 设置连接超时为 60 秒
proxy_connect_timeout 60s;
# 设置发送请求超时为 60 秒
proxy_send_timeout 60s;
# 设置读取响应超时为 60 秒
proxy_read_timeout 60s;
}
}
上述配置展示了如何在 Nginx 的 `location` 块中统一设置这三个超时参数。将值调整为 60 秒是一个常见的起始点，具体数值应根据后端服务的最大预期处理时间来设定。修改配置后，必须使用 `nginx -s reload` 命令重新加载配置才能生效。这种全局性的超时设置适用于大多数标准的 HTTP API 请求场景。
立即学习“前端免费学习笔记（深入）”；
HISUI 前端框架基础开发指南。HISUI 是基于 easyui 二次开发的 jQuery UI 组件库，专为医疗信息系统设计。当涉及 HISUI 组件开发、jQuery easyui 表格/表单/布局/窗口、医疗系统前端页面编写时使用此 skill。 涵盖 40 个组件的官方文档参考，支持声明式与编程式两种初始化方式，提供 $cm/$m 数据访问方法。
WebSocket 长连接为何频繁断开及对策
当使用 Nginx 代理 WebSocket 连接时，标准的 HTTP 超时参数往往不足以维持连接的稳定性。WebSocket 是一种全双工通信协议，客户端和服务器之间会长时间保持连接状态，期间可能没有数据传输。如果 Nginx 检测到一段时间内没有数据流动，默认的超时机制会将其视为空闲连接并强制关闭，从而导致前端应用出现“连接中断”或“心跳丢失”的现象。要解决这个问题，必须显式地配置 WebSocket 专用的超时参数，并确保正确传递 HTTP 升级头信息。
server {
listen 80;
server_name ws.example.com;
location /ws/ {
proxy_pass http://websocket_backend;
# 必须设置 HTTP 升级头，否则无法建立 WebSocket 连接
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# 针对 WebSocket 的特殊超时设置
# 设置为 0 表示禁用超时，永不关闭空闲连接
proxy_read_timeout 86400s;
proxy_send_timeout 86400s;
}
}
在 WebSocket 的配置片段中，`proxy_http_version 1.1` 是建立升级连接的前提条件。关键在于 `proxy_read_timeout` 和 `proxy_send_timeout` 的设置。这里将其设置为 86400 秒（即一天），或者根据业务需求设置为一个极大的值，甚至可以使用 0 来表示无限期等待。这样做可以确保即使在后端长时间不发送数据的情况下，Nginx 也不会主动切断连接。前端应用通常需要配合心跳机制（Heartbeat）来检测连接状态，而 Nginx 侧的宽松超时设置则是保障底层通道不断裂的基础。
当前端收到 504 错误时如何快速验证超时源
当用户在前端界面遇到请求中断或 504 错误时，首要任务是确认该错误是否确实由 Nginx 的超时机制引起，而非后端服务本身的崩溃或逻辑错误。可以通过检查 Nginx 的错误日志（error.log）来快速定位。如果日志中出现 `upstream timed out (110: Connection timed out)` 字样，且伴随具体的超时时间戳，这直接证明了是 Nginx 主动断开了连接。此时，应对比后端服务的实际处理耗时。如果后端处理仅需 2 秒，但 Nginx 配置的 `proxy_read_timeout` 为 5 秒，则说明配置合理，问题可能出在网络波动；如果后端处理需要 10 秒，而 Nginx 配置为 5 秒，则必须调大超时参数。此外，还可以使用 `curl` 命令模拟请求，通过 `-v` 参数查看详细的握手和传输过程，排除 DNS 解析或 SSL 握手阶段的潜在超时干扰。
