ThinkPHP解决文件上传大小受限的环境设置_php.ini与Nginx配置-ThinkPHP-PHP中文网

php上传失败主因是upload_max_filesize和post_max_size未同步调大，且nginx的client_max_body_size也需匹配；三者须均≥文件大小，且post_max_size≥upload_max_filesize，修改后需重启php-fpm或apache并验证生效。

thinkphp解决文件上传大小受限的环境设置_php.ini与nginx配置

PHP 上传限制：`upload_max_filesize` 和 `post_max_size` 必须同时调大

ThinkPHP 报“上传失败”或直接返回空数组，大概率不是框架问题，而是 PHP 底层拒绝接收大文件。关键在两个 ini 配置项：它们必须都 ≥ 你期望上传的文件大小，且 post_max_size ≥ upload_max_filesize（否则表单数据整体被截断）。

常见错误现象：$_FILES 为空、$_POST 也为空、ini_get('upload_max_filesize') 返回值远小于预期。

upload_max_filesize = 20M —— 控制单个上传文件最大体积
post_max_size = 25M —— 控制整个 POST 请求体上限（含文件 + 表单字段）
改完后必须重启 PHP-FPM（systemctl restart php-fpm）或 Apache，仅 reload 不生效
用 phpinfo() 页面确认修改已加载，别只改了错误的 php.ini 文件（CLI 和 Web SAPI 的配置文件常不同）

Nginx 限制：`client_max_body_size` 要覆盖所有上传入口

Nginx 在 PHP 接收到请求前就可能拦截大 POST 请求，报错通常是 413 Request Entity Too Large。这个限制独立于 PHP，必须显式配置。

使用场景：ThinkPHP 的上传接口走的是普通 HTTP POST（非 WebSocket 或分片），Nginx 默认只允许 1MB。

在 http、server 或具体 location 块中加：client_max_body_size 50M;
如果上传路由有特定路径（如 /api/upload），建议在对应 location 下设，避免全局放宽带来安全风险
若用 Nginx 反向代理到其他服务（比如上传转给 MinIO），该配置仍需保留在前端 Nginx，否则请求根本进不了代理链
改完执行 nginx -t && nginx -s reload，nginx -t 必须通过，语法错误会导致 reload 失败但无提示

ThinkPHP 自身校验：`maxSize` 参数不能绕过 PHP/Nginx 限制

框架层的 maxSize（如 $file->validate(['size' => 20971520])）只是 PHP 接收成功后的二次检查，它不解决“传不进来”的问题。

容易踩的坑：调大了 ThinkPHP 的 maxSize 却没动 php.ini，结果上传时直接卡在 PHP 解析阶段，框架根本没机会运行验证逻辑。

框架验证只对已成功写入临时目录的文件生效；若 PHP 拒绝接收，$_FILES 就是空的，$file 对象都构造不出来
ThinkPHP 6+ 中 validate() 的 size 单位是字节，别误写成 'size' => '20M'（字符串不识别）
若用 Request::file() 获取不到文件，优先查 $_FILES 是否为空，而不是立刻怀疑框架配置

调试顺序错了就白忙：先确认请求是否抵达 PHP，再查框架逻辑

上传失败时，最省时间的排查路径是：看 Nginx error log → 看 PHP error log → 打印 $_FILES → 最后才看 ThinkPHP 日志。

性能影响小但兼容性易被忽略：PHP 8.0+ 对超大 post_max_size（如 >2G）有额外内存分配策略，若设得过大又没关掉 memory_limit，可能触发 OOM 而不是明确报错。

Nginx 错误日志里搜 413 或 client intended to send too large body，有就是 Nginx 拦了
PHP 错误日志里搜 upload_max_filesize 或 exceeded post_max_size，有就是 PHP 拦了
在控制器开头加 var_dump($_FILES); exit;，空数组说明拦在了 PHP 前；有内容但 size=0 或 error=1，说明是 PHP 层拒绝
Linux 下注意 SELinux 或 AppArmor 可能限制 PHP 写临时目录（sys_get_temp_dir() 返回路径需可写）