在 macOS 上配置 Nginx 长连接与大文件上传需协同调整三类超时：客户端直连超时（client_header/body_timeout、send_timeout）、长连接控制（keepalive_timeout/requests）、反向代理超时（proxy_connect/send/read_timeout），并分链路验证调试。
在 macOS 上配置 Nginx 处理长连接或大文件上传时，超时时间设置不当会导致连接被意外中断、504 Gateway Timeout、或者前端显示“请求已取消”。关键不是单纯调大某个值，而是理解 keepalive、read/write timeout 和 proxy timeout 各自的作用，并协同调整。
一、基础超时参数：client_header_timeout、client_body_timeout、send_timeout
这三个是客户端与 Nginx 直连时的底层超时控制：
- client_header_timeout：Nginx 等待客户端发送完整 HTTP 请求头的最大时间（默认 60s）。若用户网络极慢或上传前卡顿，可能在此阶段断开。
- client_body_timeout：接收请求体（如 POST 数据、文件）期间，两次连续数据包之间的最大间隔（默认 60s）。上传大文件时，若传输速率低但持续，这个值必须足够大，否则会中断。
- send_timeout：Nginx 向客户端发送响应时，两次写操作之间的超时（默认 60s）。适用于生成缓慢的动态响应（如导出报表），非流式响应易触发。
建议在 http 或 server 块中统一设为 300（5 分钟）或更高：
client_header_timeout 300;<br>client_body_timeout 300;<br>send_timeout 300;
二、长连接核心：keepalive_timeout 与 keepalive_requests
这两个参数决定 Nginx 是否复用 TCP 连接，对前端 AJAX 轮询、WebSocket 代理、或 SPA 的资源加载影响显著：
- keepalive_timeout：客户端空闲连接保持打开的时间（默认 75s）。设为 0 则禁用长连接；设为 60–120 是常见平衡值。
- keepalive_requests：单个长连接可处理的最大请求数（默认 100）。高并发下建议调高（如 1000），避免频繁建连开销。
示例配置（放在 server 块内）：
keepalive_timeout 120;<br>keepalive_requests 1000;
三、反向代理场景：proxy_read_timeout、proxy_send_timeout、proxy_connect_timeout
如果你用 Nginx 代理后端服务（如 Node.js、Python Flask、本地开发服务器），真正耗时的是后端处理，而非 Nginx 自身。此时必须显式配置 proxy 超时：
- proxy_connect_timeout：Nginx 连接后端的超时（建议 5–10s）。
- proxy_send_timeout：Nginx 向后端发请求体的超时（如上传大文件给后端）。
- proxy_read_timeout：Nginx 等待后端响应的超时（最常需调大，如 300 表示后端有 5 分钟处理时间）。
务必放在 location 块中（尤其是针对 API 或上传路径）：
location /api/ {<br> proxy_pass http://localhost:3000;<br> proxy_connect_timeout 10;<br> proxy_send_timeout 300;<br> proxy_read_timeout 300;<br>}
四、验证与调试技巧
改完配置别急着 reload，先检查语法并观察行为：
- 执行
sudo nginx -t确保配置无误； - 用
curl -v http://localhost/your-path查看响应头中的Connection: keep-alive和Keep-Alive字段； - 模拟慢响应：启动一个延迟 4 分钟的后端接口，再用 curl 测试是否返回 504 — 若仍超时，说明
proxy_read_timeout或send_timeout仍不足； - 查看日志：
/usr/local/var/log/nginx/error.log（Homebrew 安装路径），搜索upstream timed out或client timed out可精准定位哪类超时触发。
不复杂但容易忽略。重点始终是：区分「客户端→Nginx」、「Nginx→后端」两段链路，按需分别调参。
