一次上传要穿过六层限制:upload_max_filesize 之外,那五个让 413 和 500 分不清的参数

三个月前我把主机的 upload_max_filesize 从 2M 调到 20M,以为事情就结束了。结果是:后台传 5M 的图能成功,传 8M 的包体却报「服务器内部错误」,传到 15M 时浏览器干脆一个空白页,Nginx 的 access log 里什么都没有。那天晚上我沿着整条链路查了一遍,才发现一次上传要穿过六个彼此不知道对方存在的限制,其中任何一个不满足,报错都会长得像另一个环节的问题。

这篇文章就是那次排查的完整记录。范围限定在「一个 Nginx + PHP-FPM 的 Typecho/WordPress 站」,不涉及对象存储直传,也不讨论前端分片上传——那两件事我另写。

一、先搞清楚一个上传请求要穿过哪几层

浏览器点「上传」之后,请求是这样走的:

  1. 浏览器/前端:MAX_FILE_SIZE 隐藏字段只对极老的浏览器有效,现代浏览器会在发送前就做一次 File.size 判断。
  2. CDN:绝大多数 CDN 有单请求体积上限(免费套餐常在 100M 左右),超了直接在地理节点就返回 413,源站完全看不到这个请求。
  3. Nginx:client_max_body_size,超了返回 413。这一层决定了「请求体能不能进内存/临时文件」。
  4. Nginx 临时文件:请求体超过 client_body_buffer_size 后要落盘到 client_body_temp_path,这个目录不可写或者磁盘满,会得到 500 而不是 413。
  5. PHP-FPM:把请求体转发给 PHP 时,受 fastcgi_request_buffering 与 FPM 自己的内存/超时参数影响。
  6. PHP:upload_max_filesize(单文件)、post_max_size(整个 POST 体,必须大于前者)、memory_limit(某些扩展会整块读入)、max_execution_time / max_input_time(超时)、upload_tmp_dir(临时目录空间与权限)。

关键事实:这六层的报错信息几乎无法互相归因。浏览器显示空白页说明连接被对端关掉了(Nginx 层);显示「服务器内部错误」说明进了 PHP 但抛了异常;显示 413 说明 Nginx 拦了;显示「上传文件为空」说明请求体根本没到 PHP。所以第一步永远是看日志定层,而不是继续调参数。

二、用三条命令确定是哪一层拒绝的

我最先做的是在服务器上直接用大文件打一遍,把 CDN 排除掉:

# 造一个刚好 8M 的文件
head -c 8M /dev/urandom > /tmp/t8m.bin

# 直接打源站的回环地址,绕过 CDN
curl -sS -o /dev/null -w '%{http_code} %{time_total}\n' \
  -F "file=@/tmp/t8m.bin" \
  http://127.0.0.1/upload-probe.php

# Nginx 的 error.log 里会写清楚是谁拒的
tail -50 /var/log/nginx/error.log | grep -i 'body\|too large'

如果回环能成功、走域名失败,问题就在 CDN;如果回环也 413,问题在 Nginx;如果回环 500 而 Nginx error log 里有 client intended to send too large body,那就是 client_max_body_size;如果 access log 里连请求都没有、error log 里有 prematurely closed 或者 readv() failed,那才是 PHP 侧的问题。

第二件要做的事是把 PHP 的实际上限打印出来,不要相信 php.ini 里写的那一行,因为 .user.ini、php_admin_value、以及 opcache 的配置缓存都可能让它不生效:

php -i | grep -E 'upload_max_filesize|post_max_size|memory_limit|upload_tmp_dir|max_file_uploads'
# 通过 web 打印,确认是同一份
curl -s http://127.0.0.1/probe.php | grep -E 'upload_max_filesize|post_max_size'

我遇到过的、最坑的一次是 CLI 的 php -i 显示 20M,而 web 那边还是 2M——因为 FPM 池配置里有一段 php_admin_value[upload_max_filesize] = 2M,优先级高于 php.ini。这类覆盖必须看 FPM 池文件,不在 php.ini 里。

三、几个参数之间的真实关系

下面这张表是我这次整理出来的核心,建议先背下来再改配置:

  • post_max_size 必须 ≥ upload_max_filesize。如果相等,那么「文件本身 + 表单其他字段 + multipart 边界」就会超出去,表现为「上传成功但文件为空」。留 20%~30% 余量比较稳。
  • memory_limit 不等于上传上限。上传时 PHP 默认流式写到 upload_tmp_dir,不吃内存;但如果后续要 file_get_contents 或图像处理(GD/Imagick),那一步才吃。处理 8M 的 JPEG,GD 在内存里展开后可能上百 M。
  • client_max_body_size 只用一次,但它在 http / server / location 都可以出现,就近覆盖。很多人把值写在 http 块里,然后某个 /upload 的 location 里加了另一行更小的,一直以为没生效。
  • max_execution_time 只管 PHP 脚本自身的执行时间。上传过程(浏览器往服务器传字节)算的是 max_input_time,Nginx 那边则受 client_body_timeout 约束——而且它是「两次读之间的间隔」,不是总时长。
  • fastcgi_request_buffering off 会改变行为。默认是 on,Nginx 会先把整个请求体缓冲完再转给 FPM;关掉之后是流式转发,FPM 端看到的连接时间会变长。大文件上传时这个开关直接影响 max_input_time 会不会被触发。

四、磁盘和临时目录:最容易忽略的一层

参数都调对了,还有一个必查项:临时目录能不能写、空间够不够、和主站是否同一个分区。

# Nginx 的临时目录
nginx -T | grep client_body_temp_path
df -h /var/lib/nginx/body

# PHP 的临时目录
php -r 'echo ini_get("upload_tmp_dir"), PHP_EOL;'
df -h /tmp

# FPM 池的用户是 www-data,确认它对该目录可写
sudo -u www-data touch /tmp/_w && echo writable; rm -f /tmp/_w

我见过两种典型事故。第一种是 /var 分区只有 8G,日志和上传临时文件堆到满,之后所有上传都 500,而 df -h / 看起来还有空间——因为满的是 /var,不是 /。第二种是 /tmp 被挂成了 noexec,nosuid(很多安全加固模板默认会这么干),PHP 上传本身没问题,但某些库会尝试在临时目录执行检查程序,于是一上传就崩。

还有一个隐蔽项:upload_tmp_dir 如果设成 PHP 本来就用不到的路径(比如容器里没有挂载的那个路径),PHP 会静默回落到系统 /tmp,你以为改好了,其实没有。用上面的 phpinfo 输出核对,而不是 ps aux | grep fpm。

五、容器与代理环境下的额外两层

我的站后来迁到了 Docker 里,参数全部覆盖了一遍,然后问题又回来了。原因有两类:

第一类是反向代理的缓冲。Docker 里跑 Nginx 作为入口,应用容器里的另一个 Nginx 或者 PHP 内置服务器做后端。两段 Nginx 各有一个 client_max_body_size,前者调了后者没调,照样 413。另外 proxy_request_buffering off 只在你想让大文件流式到位时才有必要,开了之后上游的超时要能撑得住,否则会出现「传到 80% 被上游断掉」的现象。

第二类是挂载与用户。容器里 upload_tmp_dir 指向的卷如果只读挂载,或者宿主机的目录权限是 root:root 755 而容器里跑的是 www-data,就会得到「上传失败但日志里没有明显错误」。这类问题要一次看三层:宿主目录权限、容器内挂载点权限、进程实际 uid,三个都对上才通。

# 一眼看全
docker inspect -f '{{range .Mounts}}{{.Source}} -> {{.Destination}} rw={{.RW}}{{"\n"}}{{end}}' 容器名
docker exec -u www-data 容器名 sh -c 'touch /var/tmp/up/_t && echo ok && rm /var/tmp/up/_t'

另外别忘了 CDN 那一层,尤其是你开了「上传加速」或者单独的上传子域名后,体积上限往往是单独配置的,和主站不是一套。

六、一次上传被中断时,数据去哪了

「传到 90% 断了,下次要重传」这件事的必要性,取决于你知道数据分布在哪。默认情况下:

  • Nginx 在 client_body_temp_path 下建一个临时文件,只有请求体完整接收后才会交给上游;
  • PHP 在 upload_tmp_dir 里再存一份 php*.tmp,脚本结束(成功或失败)时由 PHP 自动删除;
  • 你的业务代码只有执行 move_uploaded_file 之后,文件才真正落在站点目录里。

所以一次中断的上传会在磁盘上留下两个孤儿:Nginx 的临时文件(由 client_body_timeout 触发清理)与 PHP 的 php*.tmp(脚本正常退出时清理,进程被 kill 时不会)。这也是为什么我建议把这个目录单独监控体积,设置一条「超过 2G 或者单文件超过 1 小时就报警」的规则——它不是空间问题,而是「有大量中断请求」的信号。

七、正确的参数改法:一次改一层,改完就验

最省时间的顺序不是把所有参数一次调大,而是按「哪层最容易拦住」逐层放开,每放开一层立刻用同一份测试文件验证一遍:

# 顺序:Nginx → FPM → PHP
client_max_body_size 32m;         # nginx.conf server 块
client_body_buffer_size 256k;     # 超出部分落盘
client_body_timeout 30s;

# FPM 池
php_admin_value[post_max_size] = 30M
php_admin_value[upload_max_filesize] = 24M
php_admin_value[max_input_time] = 300
php_admin_value[memory_limit] = 256M

# php.ini 里只保留和 FPM 一致的值,避免出现两套

每改完一层就 nginx -t && nginx -s reload / systemctl reload php-fpm,然后用 8M、16M、24M、30M 四个体积分别打一遍,记录状态码。这样出问题时你能精确知道是第几层,而不是像最初的我一样在半夜里改第七个参数。

验证完成之后,别忘了把改动写进版本库。这些配置分散在 nginx.conf、站点 conf、FPM 池、php.ini、.user.ini 五处,不记下来,下次换机器一定会漏掉其中一处——而漏掉的那一处恰好就是上线后第一个报错的地方。

八、结语:报错文案不可信,链路才可信

这次排查我最大的收获不是记住了哪个参数该设多大,而是认识到:上传类故障的报错文案,几乎总是归因错误的那一层。浏览器说的是「服务器内部错误」,其实是 Nginx 关了连接;Nginx 的 access log 说 200,其实是 PHP 拿到了一个空文件;PHP 说「上传失败」,其实是临时目录不可写。

所以遇到这类问题,别改参数,先打三个点:回环直连看状态码、看两层日志里的关键行、打印 web 侧的真实 ini 值。三件事做完,问题基本自己就浮出来了。剩下的只是按顺序把六层的上限抬到同一个数量级——既不浪费内存,也不留一个突然炸掉的天花板。

Last modification:November 20th, 2026 at 12:25 pm

Leave a Comment