Nginx大文件上传调优教程指南

Nginx 默认限制客户端请求体大小为 1MB，所以上传大文件时经常遇到 413 Request Entity Too Large，或者上传到一半连接中断、响应超时。
本文围绕 Nginx 大文件上传调优中的 client_max_body_size 和超时参数，教你通过修改配置文件，让单个文件上传上限和传输稳定性满足业务需要。
内容按零基础可操作的方式展开，直接复制命令即可跟着做。

调优前先确认这两件事

第一，确认当前 Nginx 配置文件位置和是否做过其它自定义。
多数通过包管理器安装的 Nginx，主配置文件在 /etc/nginx/nginx.conf，站点配置通常在 /etc/nginx/conf.d/ 或 /etc/nginx/sites-available/。
如果你使用宝塔面板，可以直接在“软件商店 - Nginx - 配置修改”中编辑，但更推荐在站点设置里添加自定义配置片段。

第二，修改前一定要备份原配置，避免改错后无法回退。
执行下面命令：

cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak

如果是通过宝塔修改，也可以先复制一份完整的 nginx.conf 内容到本地保存。
备份之后再动手调优，后面出错也不慌。

第一步：提高 client_max_body_size 上传大小限制

client_max_body_size 是 Nginx 允许客户端请求体最大字节数，默认 1m。
你需要把它调整成业务允许的最大文件尺寸，比如允许上传 100MB：

client_max_body_size 100m;

这个指令可以写在 http、server 或 location 块中。
我建议优先放在 server 块或具体的 location /upload 块里，避免整个服务器所有站点都放开到很大值，减少资源浪费。

修改后先检查配置语法，再重新加载 Nginx：

nginx -t && nginx -s reload

如果输出 syntax is ok 和 test is successful，说明配置没有问题。
注意：只改配置文件不 reload，新配置不会生效。

第二步：配合调整请求体和响应超时参数

只调大 client_max_body_size 还不够，大文件在上传过程中需要更长传输时间，以下几个参数也很关键。

• client_body_timeout：Nginx 读取请求体超时时间，默认 60 秒。大文件上传建议调大到 300 秒以上。
• client_body_buffer_size：请求体缓冲大小，默认 8k 或 16k。如果上传的请求头或小表单比较大，可以适当调大，但它不决定文件大小上限。
• client_body_temp_path：请求体临时写入目录，大文件上传时会先写到这里。默认路径在 /var/cache/nginx/client_temp，需要保证磁盘空间充足。

如果 Nginx 反向代理到后端服务，还需要关注 proxy_read_timeout 和 proxy_send_timeout，它们控制 Nginx 与后端服务器之间的读、写超时。
一个比较稳妥的配置片段如下：

client_max_body_size 100m;
client_body_timeout 300s;
client_body_buffer_size 16k;
client_body_temp_path /tmp/client_body_temp;

proxy_read_timeout 300s;
proxy_send_timeout 300s;

其中 client_body_temp_path 是指定的临时目录，你需要提前建好并保证权限可写：

mkdir -p /tmp/client_body_temp
chown -R nginx:nginx /tmp/client_body_temp

如果使用宝塔面板，也可以直接在配置文件里加这些指令，但要注意 client_body_temp_path 不要和系统其它站点冲突。

第三步：别忘了后端服务的限制

很多时候前端 Nginx 已经放开了，但上传依然失败，问题往往出在后端。
以 PHP 环境为例，你还需要同步调整 PHP 的 php.ini 参数：

upload_max_filesize = 100M
post_max_size = 100M
max_execution_time = 300
max_input_time = 300

如果是宝塔面板，可以在“PHP 设置 - 配置修改”中调整，保存后会自动重载。
使用 PHP-FPM 时，别再忽略 request_terminate_timeout，这个参数默认 60 秒，大文件上传或后端处理超过该时间会被强制结束，导致前端返回 504 Gateway Time-out。

如果你的 Nginx 只是反向代理到 Java、Go 等后端，同样需要确认后端应用的上传体积限制和请求超时配置，例如 Spring Boot 的 spring.servlet.multipart.max-file-size，或者 Go 的 http.MaxBytesReader。
前后端任何一处没放开，都会让大文件上传失败。

高频报错与避坑

413 Request Entity Too Large
最常见的错误。优先检查 client_max_body_size 是否写在了真正生效的 server/location 中。例如某个 location 里面另外设置了更小的值，就会覆盖外层。另外确认修改后是否执行了 reload。如果你配置了 CDN 或前置负载均衡，还需要在对应代理层也调大请求体限制。

504 Gateway Time-out
后端处理时间太长。先确认 proxy_read_timeout 和 proxy_send_timeout 是否足够，再检查 PHP-FPM 的 request_terminate_timeout 或后端服务的读取超时。很多情况下，两者的超时时间要大于你预期的上传耗时。

上传到一半中断
可能原因有三类：一是 client_body_timeout 太短，二是 client_body_temp_path 所在磁盘空间不足，三是临时目录没有写权限。用 df -h 检查磁盘，用 ls -ld /tmp/client_body_temp 确认权限。上传文件很大时，Nginx 会先把请求体写入临时文件，如果磁盘满了，连接就会中断。

反向代理缓冲问题
如果你使用了反向代理，且后端希望直接读取原始请求体，可以考虑关闭请求体缓冲：

proxy_request_buffering off;

开启 off 后，Nginx 会把客户端数据直接传给后端，不再先完整缓冲到临时文件。
对于大文件上传，这种模式能减少磁盘 IO，但也会让上游很快开始接收数据，对后端稳定性要求更高。
建议根据业务情况取舍。

验证调优结果

修改完成后，先执行 nginx -t 确认语法正确，再 nginx -s reload 重载。
然后可以用下面方式验证：

1. 使用 nginx -T 查看实际生效的配置，确认 client_max_body_size 是你设置的值。
2. 用 curl 模拟上传本地大文件，观察返回码：

curl -F "file=@/path/to/largefile.zip" https://yourdomain.com/upload -w "%{http_code}"

如果返回 200 或业务规定的成功状态码，说明上传链路正常。
如果仍返回 413 或 504，打开 Nginx 错误日志继续排错：

tail -f /var/log/nginx/error.log

日志中的 client intended to send too large body 对应 413，upstream timed out 对应 504，
根据日志提示去调整对应参数即可。

调优 Nginx 大文件上传时，client_max_body_size 和超时参数是核心，但一定要同步关注后端限制、临时目录空间和代理层配置。
建议改完用真实业务的大文件压测，同时观察服务器负载和磁盘占用。
如果你正在处理这个问题，按本文步骤从备份到验证完整走一遍，遇到异常优先回看上面避坑和常见报错部分，大部分问题都能定位到具体参数。