上传失败应先检查$_FILES是否为空，若为空则排查表单enctype、FormData、Web服务器及PHP上传限制；若不为空则检查目标目录权限、跨文件系统问题及Filesystem驱动配置。
上传失败时先看 $_FILES 是否为空
很多“上传失败”其实根本没走到 ThinkPHP 的逻辑层，$_FILES 已经是空数组。这说明请求压根没把文件送进来，和框架无关。
检查方法：在控制器开头加一行 var_dump($_FILES); die;，上传后看输出。如果为空，重点排查：
- 表单
<form></form>缺少enctype="multipart/form-data" - 前端用 JS 上传时，
FormData没正确 append 文件（比如 key 名和后端接收名不一致） - Nginx 或 Apache 配置了过小的
client_max_body_size或LimitRequestBody，直接拦截大文件 - PHP 自身限制：
upload_max_filesize和post_max_size不匹配（后者必须 ≥ 前者 + 其他表单字段体积）
ThinkPHP 的 moveTo() 报错常见原因
如果 $_FILES 有数据，但调用 $file->moveTo($path) 失败，错误通常是 move_uploaded_file(): Unable to move... 类型。这不是 ThinkPHP 的 bug，而是 PHP 底层移动失败。
核心原因只有两个方向：
立即学习“PHP免费学习笔记（深入）”；
-
目标目录不存在或不可写：ThinkPHP 不会自动创建多级目录，
$file->move('uploads')要求uploads/目录已存在且 Web 进程用户（如 www-data、nginx、apache）有写权限 -
目标路径跨磁盘或挂载点：某些 Linux 环境下，
move_uploaded_file()不支持跨文件系统移动，需改用copy() + unlink()组合（但 ThinkPHP 默认不用这种方式）
实操建议：上传前手动执行 mkdir -p runtime/upload && chown -R www-data:www-data runtime/upload，并确认 runtime/ 在 upload 配置中被允许（查看 config/filesystem.php 中 default 对应的 disk）
Filesystem 驱动配置影响上传路径解析
ThinkPHP 6+ 使用 think\filesystem\Filesystem 管理上传，$file->store() 或 $file->storeAs() 的行为依赖 config/filesystem.php 里 disk 的配置。
容易踩的坑：
-
'root' => 'public/uploads'是相对路径，实际根目录是public_path('uploads')，不是ROOT_PATH . 'public/uploads' - 使用
local驱动时，'url' => '/uploads'只用于生成访问 URL，不影响保存位置；但若配错，会导致前端拿到 404 链接 - 切换到
qiniu或oss驱动后，moveTo()会失效——它只适用于 local 驱动，远程驱动必须用store()
验证方式：打印 $file->store('images') 返回值，正常应为类似 images/xxx.jpg 的相对路径；如果返回 false 或抛异常，立刻检查对应 disk 的 root 目录是否存在且可写
调试时别忽略临时目录 sys_get_temp_dir()
PHP 上传文件先存到系统临时目录（由 sys_get_temp_dir() 返回），再由 move_uploaded_file() 移出。如果这个临时目录满了、无写权限或被 SELinux 限制，上传会静默失败（$_FILES 为空或 error=2）。
查法很简单：
- 在任意控制器里加
echo sys_get_temp_dir();，看路径是否合理（如/tmp、/var/tmp） - 执行
ls -ld $(sys_get_temp_dir())，确认权限为drwxrwxrwt（带 t 位）且磁盘未满 - CentOS/RHEL 上运行
getsebool httpd_can_network_connect，如为 off，可能需开启：setsebool -P httpd_can_network_connect on
这个环节最容易被跳过，但恰恰是很多“上传突然不行了”的根源——尤其服务器管理员清过 tmp 或更新过安全策略之后
