PHP上传失败主因是upload_max_filesize和post_max_size未同步调大，且Nginx的client_max_body_size也需匹配；三者须均≥文件大小，且post_max_size≥upload_max_filesize，修改后需重启PHP-FPM或Apache并验证生效。
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。
立即学习“PHP免费学习笔记（深入）”；
- 在
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()返回路径需可写）
php.ini 放错目录拖半天。 
