PHP 上传失败怎样区分两个大小限制

我排查 PHP 文件上传失败时，通常先看两个值：upload_max_filesize 管单个文件，post_max_size 管整次 POST 请求。前者设置得再大，如果后者没有留下足够余量，包含文件和表单字段的 multipart/form-data 请求仍然会在 PHP 解析阶段被挡住。

官方地址：https://www.php.net/manual/en/ini.core.php

判断口诀是：单个文件超限，优先看 upload_max_filesize；整次请求超限，重点看 post_max_size。为了让上传可用，post_max_size 必须大于 upload_max_filesize，并且两项要在真正生效的 INI 层级修改。

• upload_max_filesize：一个文件允许的最大尺寸。
• post_max_size：一次 POST 数据允许的总尺寸，包含文件和其它表单字段。
• 整次 POST 超过上限时，$_POST 和 $_FILES 可能都是空的。
• 两项都是 INI_PERDIR，不要把 ini_set() 当成上传限额修复。

先区分两个限制的作用域

upload_max_filesize 看的是“一个文件有多大”，例如表单里有两个文件时，它分别约束每一个文件；post_max_size 看的是“这一整次 POST 有多大”，除了文件，还要包含 multipart 边界、文件名、其它字段和请求头对应的数据。

因此两项不是并列的同一个阈值，而是嵌套在不同层级。PHP 官方手册明确说明，post_max_size 也会影响文件上传，并且必须大于 upload_max_filesize。如果目标是允许单个 20M 文件，直接把两项都写成 20M 并不稳妥，POST 总量至少要留出额外空间。

用请求现象判断哪一项先触发

排查时不要只看前端的“上传失败”。如果单个文件超过 upload_max_filesize，PHP 通常仍会创建对应的 $_FILES 项，并在其中留下 UPLOAD_ERR_INI_SIZE 这类错误状态；这时应用有机会把错误翻译成“单文件过大”。

如果整次 POST 已经超过 post_max_size，PHP 手册提示 $_POST 和 $_FILES 可能为空。此时业务控制器连文件项都拿不到，不能再用“文件字段缺失”去掩盖配置问题。可以给表单加一个普通的查询参数作为请求标记，进入处理脚本后检查该标记是否存在，辅助识别请求是否在解析阶段被截断。

先把两项配置设成有余量的一组

假设业务希望单个文件最多 20M，可以把文件限制设为 20M，再把 POST 限制设为更大的值，例如 24M 或 32M。具体余量取决于同一个表单里是否还会提交描述、批量文件和其它字段，不能只按文件大小机械相等。

; 单个文件上限，控制每个上传文件的最大尺寸
upload_max_filesize = 20M

; 整次 POST 上限，要覆盖文件、表单字段和 multipart 开销
post_max_size = 32M

这两项在 PHP 手册中都是 INI_PERDIR，可在主 php.ini、Apache 目录配置或适用的 .user.ini 中设置，具体位置取决于 PHP 的 SAPI 和服务器配置。修改后要让对应的 PHP 进程重新读取配置；只改了 CLI 使用的配置文件，不代表 Web 请求使用的配置也变了。

用 PHP 读取当前真正生效的值

我更习惯先在与上传请求相同的 Web 运行环境里读取配置，而不是猜测服务器加载了哪个文件。ini_get() 返回的是配置中的字符串，像 20M 这样的简写不会自动变成整数；下面的检查只用于显示当前值，不尝试在脚本内修改它。

如果读取结果和你编辑的文件不同，先确认请求经过的是哪一个 PHP-FPM 池、Apache 模块或 CGI/FastCGI 进程，再检查对应的配置层级。不要用页面里的 ini_set('upload_max_filesize', '32M') 期待放大上传上限，因为这两项不是可以在脚本运行时随意改变的 INI_ALL 选项。

在应用层保留可解释的上传错误

配置解决的是“请求能否被 PHP 接收”，业务代码仍然要检查 $_FILES 中的错误码、临时文件和业务允许的扩展名。下面的示例只处理两个大小限制相关的分支：单文件超限时读取文件项错误；整次 POST 超限导致文件集合为空时，给出配置排查提示。

常见问题

两个值必须设置成一样吗？

不应该。post_max_size 要大于 upload_max_filesize，因为 POST 还包含 multipart 结构和其它字段。批量上传时还要按一次请求的总文件量重新估算。

为什么超大请求时 $_FILES 是空数组？

如果整个 POST 数据超过 post_max_size，PHP 可能在填充超全局变量前就停止解析，所以 $_POST 和 $_FILES 都可能为空。此时优先检查当前生效的配置，而不是只改应用层错误提示。

可以用 ini_set() 临时解决吗？

通常不行。两项配置属于 INI_PERDIR，应在允许的目录或服务器配置层设置。页面内最多读取和记录它们的当前值，不能把脚本运行时设置当成部署配置。

设置改了但上传仍失败怎么办？

用同一个 Web 入口读取 ini_get()，确认实际 PHP 进程看到的新值；再检查是否一次上传了多个文件，以及应用是否还有独立的业务大小校验。这样能把 PHP 层限制和业务层限制分开。

把两个配置按作用域拆开，上传排错就会清晰很多：先用 upload_max_filesize 判断单文件，再用 post_max_size 判断整次请求，最后用当前 Web 环境的 ini_get() 结果确认修改确实生效。