ThinkPHP上传失败多数因PHP或Web服务器底层拦截，应先检查$_FILES是否为空：为空则排查表单enctype、FormData键名、Nginx client_max_body_size及PHP upload_max_filesize/post_max_size配置；不为空则检查目标目录权限、是否存在及是否跨文件系统。
ThinkPHP 文件上传失败，多数情况不是框架本身的问题，而是 PHP 或 Web 服务器在底层就拦截或中断了请求。排查要从 $_FILES 是否为空开始，分两层定位：文件根本没进来，还是进来后存不下去。
先看 $_FILES 是否为空
这是最关键的一步。在控制器开头加一行：
var_dump($_FILES); die;如果输出是空数组，说明文件压根没传到 PHP，和 ThinkPHP 逻辑无关。重点检查：
- 表单
<form></form>缺少enctype="multipart/form-data" - 前端用 JS 上传时，
FormData.append()的 key 名和后端request()->file('xxx')的字段名不一致 - Nginx 配置中
client_max_body_size过小（默认仅 1MB），超限直接返回 413，请求根本不到 PHP - PHP 配置中
file_uploads = Off、upload_max_filesize或post_max_size设置过小，且post_max_size 会导致静默失败
$_FILES 有数据但 moveTo() 失败
此时错误通常是 move_uploaded_file(): Unable to move。核心原因只有两个方向：
立即学习“PHP免费学习笔记（深入）”；
- 目标目录不存在，或 Web 进程用户（如
www-data、nginx）无写权限 —— ThinkPHP 不会自动创建多级目录，需手动mkdir -p uploads并chown -R www-data:www-data uploads - 目标路径跨文件系统（比如从
/tmp移到挂载的 NFS 盘），move_uploaded_file()不支持，需改用copy() + unlink()（但 ThinkPHP 默认不用这种方式）
注意：$file->move('uploads') 中的 uploads 是相对路径，实际保存位置由 config/filesystem.php 中 disk 的 'root' 决定，不是随便写个路径就能生效。
别忽略 PHP 底层临时目录问题
报错 Missing temporary folder 或 UPLOAD_ERR_NO_TMP_DIR（错误码 6），说明 PHP 接收文件的第一步就失败了：
- 检查
phpinfo()中upload_tmp_dir是否为空或路径不存在 - 显式设置
upload_tmp_dir = /var/www/tmp，并确保该目录存在、可写、且在open_basedir白名单内 - Linux 下还要留意 SELinux 或 AppArmor 是否拦截，可临时执行
setenforce 0验证
这个阶段失败，ThinkPHP 根本拿不到文件对象，所有框架层的验证、移动操作都还没开始。
Windows 和扩展相关坑
在 Windows（尤其是 Win11 + PHP 8.0+）环境下，常见静默失败是因为 fileinfo 扩展未启用：
- 运行
php --ini查 CLI 实际加载的 php.ini 路径（不是 phpinfo 页面显示的那个） - 编辑该文件，取消注释
extension=fileinfo，确认extension_dir指向正确，且php_fileinfo.dll真实存在 - 重启 PHP-FPM 或 Web 服务后，用
php -m | findstr fileinfo和 phpinfo 页面双重验证
没有 fileinfo，finfo_open() 调用失败，部分验证（如 mime 类型检查）会出问题，甚至导致 getError() 返回空。
