ThinkPHP文件上传失败主因是PHP配置或表单错误：$_FILES为空需检查enctype、method、name及file_uploads=On；error=1或空白需调大upload_max_filesize和post_max_size并重启PHP-FPM；moveTo()失败需确认目标目录权限、存在性及upload_tmp_dir状态。
ThinkPHP 文件上传失败，八成不是框架写错了，而是 PHP 底层配置没开、表单没写对，或临时目录卡住了。直接改代码前，先查 $_FILES 是不是空的、file_uploads 是不是 On、enctype 有没有漏。
$_FILES 为空或 error=4，先盯表单和 PHP 基础开关
这是最常被跳过的一步：表单根本没把文件送进来，后面所有验证、移动都白搭。
-
enctype="multipart/form-data"必须写在<form>标签上，少一个字符都不行 -
<input type="file" name="avatar">的name值，要和$request->file('avatar')里的字符串完全一致（大小写敏感） - 确认是
method="POST"，GET 不传文件 -
file_uploads = On在 php.ini 中必须启用，否则整个上传通道被物理关闭 - 用
phpinfo()或ini_get('file_uploads')确认生效路径——Nginx + PHP-FPM 场景下，/etc/php/8.1/fpm/php.ini和/etc/php/8.1/cli/php.ini是两份文件
报错 UPLOAD_ERR_INI_SIZE（error=1）或静默空白，检查 upload_max_filesize 和 post_max_size
PHP 在解析请求体时，会先按 post_max_size 截断整个 POST 数据，哪怕你只传一个文件、没其他字段。所以只调大 upload_max_filesize 没用。
-
upload_max_filesize = 128M（按你要传的最大单文件设） -
post_max_size = 135M（必须 ≥upload_max_filesize，建议多留 5–10M 余量） - 改完必须重启 PHP-FPM（
systemctl restart php8.1-fpm），不是 reload Nginx - 如果页面直接空白、
$_FILES和$_POST都空，但 Nginx access log 没 413，大概率就是post_max_size被截了
moveTo() 失败但 error=0，问题在目标路径或临时目录
$_FILES['xxx']['error'] === 0 只代表 PHP 成功接收到并暂存了文件，不代表能存到你指定的位置。
立即学习“PHP免费学习笔记（深入）”；
- 目标目录必须存在，
moveTo()不会自动创建父级目录，得提前mkdir($dir, 0755, true) - 确认 Web 进程用户（如
www-data）对目标目录有写权限：ls -ld uploads/看权限位，chown www-data:www-data uploads/改归属 -
upload_tmp_dir指向的路径（默认系统/tmp）必须可写、有空间、没被 SELinux 拦住；可用df -h /tmp和ausearch -m avc -ts recent排查 - Windows 下别用反斜杠拼路径：
'uploads\'. $file->hash()→ 改成'uploads/' . $file->hash()或用DIRECTORY_SEPARATOR
validateRule() 不生效或 catch 不到 _ValidateException，注意调用时机和命名
ThinkPHP 的上传验证不是模型验证，也不是靠 try/catch 普通异常就能兜住的。
- 必须用
$file->validateRule(['size'=>2097152,'ext'=>'jpg,png'])，不是$model->validate() - 验证失败抛的是
\think\exception\_ValidateException（开头带反斜杠和下划线），IDE 不提示，漏写命名空间就捕获不到 - 正确写法：
catch (\think\exception\_ValidateException $e)；错误写法：catch (ValidateException $e)或catch (_ValidateException $e) - 别依赖全局异常处理器统一捕获——这个异常在验证阶段就被吞掉，进不了
Handle::render()，得在控制器里对每个$request->file()单独 try/catch
上传链路上每一步都有自己的“责任区”：浏览器负责发对、PHP 配置负责收进、临时目录负责存稳、ThinkPHP 负责验和移。任何一个环节权限、路径、配置没对齐，都会表现为“上传失败”，但错误现象可能完全一样。最容易被忽略的是 post_max_size 和 upload_tmp_dir 的实际状态——它们不报错，只沉默丢数据。
