PHP 文件上传大小限制的多层配置排查

PHP 文件上传失败时，先不要只把 upload_max_filesize 调大。一个上传请求至少会经过请求体上限、单文件上限和应用层校验三道边界：post_max_size 约束整个 POST 数据，upload_max_filesize 约束单个文件，业务代码还可能再次限制扩展名、字节数或错误码。

因此，最短排查路径是先比较两个 PHP 配置，再确认当前 SAPI 读到的值，最后查看 $_FILES['file']['error']。官方参考地址：https://www.php.net/manual/en/ini.core.php

先区分两个 PHP 核心上限

post_max_size 面向一次请求的 POST 数据总量，文件、普通表单字段以及 multipart 边界都包含在这个范围内；upload_max_filesize 面向单个上传文件。PHP 官方文档明确要求前者大于后者，实际配置可以留出少量请求开销，例如目标单文件为 20M 时，将请求体设置为 24M 或更高。

配置的最小组合可以写成：

; 整个 multipart 请求要比单文件上限更宽松
post_max_size = 24M

; 只限制单个上传文件的大小
upload_max_filesize = 20M

; 允许 PHP 使用的临时上传目录必须可写
upload_tmp_dir = /var/lib/php/uploads

如果 post_max_size 太小，超限请求可能让 $_POST 和 $_FILES 都为空；如果只是某个文件超过 upload_max_filesize，通常还能从文件条目中看到对应错误码。两种现象不要用同一个“文件太大”提示覆盖。

确认当前运行层真正读到的配置

改了配置文件却没有效果，常见原因是改到了 CLI 使用的 php.ini，而网站请求走的是 PHP-FPM 或 Apache 模块。可以在诊断页中读取当前 SAPI 的值，再对照服务重载后的结果：

\n", $key, htmlspecialchars((string) ini_get($key), ENT_QUOTES, 'UTF-8'));
}

// 诊断页使用后应删除或限制访问，避免泄露环境配置。
?>

如果返回值仍旧没有变化，依次检查当前 Web SAPI 的配置路径、配置文件中的重复项和 PHP-FPM/Apache 是否已重新加载。不要把“文件上传控件显示了 20M”当作 PHP 已生效的证据，浏览器端提示只能说明前端展示值。

检查应用层校验和错误码

PHP 会把上传结果放在 $_FILES 中，应用代码应先判断错误码，再读取大小和临时文件。特别是请求体整体超限时，文件条目可能不存在，所以要区分“没有文件”和“配置层让请求体被截断”的场景。

 $businessLimit) {
    http_response_code(413);
    exit('文件超过业务允许大小');
}

// 通过错误码和业务限制后，再进入保存与后续类型校验。
echo '文件大小检查通过';
?>

表单中的 MAX_FILE_SIZE 可以作为用户体验提示，但不能代替服务端配置和业务校验。应用还应继续检查文件类型、保存目录权限和最终落盘策略；这些属于上传安全与业务边界，不应混写成 PHP 核心大小限制。

按现象选择要改的层

把“请求体上限、单文件上限、业务上限”分别记录下来，排查时就能快速判断哪一层先拒绝。修改后只需要复查当前 Web 请求读到的配置和应用返回的错误码，不要用客户端控件的显示值替代服务器端证据。

常见问题

为什么 upload_max_filesize 调大了仍然上传失败？

先检查 post_max_size 是否更大，再确认修改的是网站请求使用的 SAPI 配置，并检查 PHP-FPM 或 Apache 是否重新加载。

post_max_size 超限时为什么看不到错误码？

整个请求体被 PHP 判定为超限时，$_POST 和 $_FILES 可能都是空的，应用需要结合字段存在性和请求入口参数识别这一层问题。

业务层还需要限制文件大小吗？

需要。PHP 配置负责请求接收边界，业务层负责用户、接口或场景的具体规则，两者应该同时保留并返回可区分的错误信息。