nginx大文件传输超时需分阶段精准配置：客户端侧设client_header_timeout和client_body_timeout控制接收耐心；代理侧按后端p95响应时间+20%设proxy_read_timeout，流式导出需关proxy_buffering并设≥3600s；连接层keepalive_timeout建议60–600s，keepalive_requests设100–1000；配套需在location块设client_max_body_size、调优buffer大小及确保临时目录权限。
限制 Nginx 传输大文件时的超时时间，本质不是“一刀切地拉长所有 timeout”，而是针对数据流动的不同阶段，分角色、分路径精准设值。配错一个参数，轻则上传中断报 504/408，重则连接堆积、worker 被卡死。
客户端侧：控制请求头和请求体接收耐心
这两个参数决定 Nginx 是否愿意等你把文件发完：
- client_header_timeout：等待完整 HTTP 请求头的最大空闲时间。弱网或移动端建议设为 60s，防 TLS 握手或代理重传拖慢 header 到达
- client_body_timeout：两次 TCP 数据包之间允许的最大间隔（不是总上传时长）。上传百 MB 文件时，设 300s（5 分钟）可支持断点续传节奏；纯后台系统可设 30s～120s，视网络质量动态调整
代理侧：匹配后端真实响应能力
proxy_read_timeout 是大文件传输中最容易误配的关键项：
- 它不是“整个请求最长等多久”，而是“Nginx 从 upstream 开始读响应起，连续等待数据的最大时长”
- 先用
curl -w "@format.txt" -o /dev/null -s http://your-api测后端接口 P95 响应时间（比如 78s），再加 20% 余量 → 设为 proxy_read_timeout 95s - 流式导出（如 CSV/SSE）必须关缓冲：proxy_buffering off，且 proxy_read_timeout ≥ 3600（1 小时），否则连接会被提前切断
- proxy_connect_timeout 建议 5s～15s；proxy_send_timeout 可压至 30s～60s，它只在 upstream 拒绝接收请求时触发，无需比 read 更长
连接生命周期：防连接堆积与资源耗尽
keepalive 相关参数影响复用效率和连接数上限：
- keepalive_timeout：设为 60s～600s，根据业务类型区分——普通 API 用 60s，后台导入类长任务可设 600s
- keepalive_requests：建议设 100～1000，避免单连接无限复用导致内存泄漏或 worker 阻塞
- 若用 upstream 模块，记得加 keepalive 32;（或更高），并确保后端服务支持长连接复用
配套动作不能漏：光调 timeout 不顶用
大文件传输失败，常因配套机制没跟上：
-
client_max_body_size 必须写在匹配上传路径的
location块里，例如：location /api/upload { client_max_body_size 500m; ... }，放 http 或 server 块无效 - client_body_buffer_size 建议设为 512k～1m；太小会频繁刷盘，太大浪费内存
- 确认 client_body_temp_path 对应目录磁盘空间充足，且 Nginx 运行用户（如 www-data）有读写权限，否则报
Permission denied - 修改后务必执行
nginx -t校验配置，再nginx -s reload生效
