ThinkPHP 7.2 图片上传失败90%源于环境配置：$_FILES为空需查enctype、file_uploads、Nginx client_max_body_size；moveTo()失败需确保目录存在、可写、同文件系统；用Filesystem驱动时须改用store()而非moveTo()；大文件需调大Nginx及PHP超时参数。
ThinkPHP 7.2 安装后图片上传失败，90% 不是框架本身的问题，而是 PHP 运行环境或 Web 服务器在请求抵达框架前就拦截或丢弃了文件——$_FILES 为空、move_uploaded_file() 报错、或前端收不到响应，基本都指向这层。
先看 $_FILES 是不是空的
这是最该优先确认的一点。如果 $_FILES 是空数组，说明文件根本没进 PHP，ThinkPHP 根本没机会执行任何逻辑。
- 检查表单是否带
enctype="multipart/form-data"，漏掉这个属性，浏览器就不会发文件数据 - 前端用
FormData时，确保append('file', input.files[0])的 key（这里是file）和后端Request::file('file')里的字段名一致 - 运行
phpinfo()，确认file_uploads = On、upload_max_filesize和post_max_size已生效，且后者 ≥ 前者 + 其他表单字段体积 - Nginx 用户必须检查
client_max_body_size是否在server块中显式配置（如client_max_body_size 50M;），全局 http 块里设无效
moveTo() 报 Unable to move 怎么办
当 $_FILES 有数据但 $file->moveTo($path) 失败，错误本质是 PHP 底层移动失败，不是 ThinkPHP bug。
-
$path对应的目录必须已存在，ThinkPHP 不会递归创建多级路径；例如想存到uploads/images/2026/09/，得提前mkdir -p uploads/images/2026/09 - 目标目录需对 Web 进程用户（如
www-data、nginx）可写：chown -R www-data:www-data uploads+chmod -R 755 uploads - Linux 下若
upload_tmp_dir和目标目录跨文件系统（比如 tmp 在/tmp，uploads 在/data），move_uploaded_file()会静默失败；可临时改upload_tmp_dir = /data/tmp并授予权限 - Windows 用户注意路径分隔符，
moveTo('uploads\'. $file->hash())中的反斜杠可能被误解析，统一用/或DIRECTORY_SEPARATOR
用了 Filesystem 驱动却还在调 moveTo()
ThinkPHP 7.2 默认启用 think\filesystem\Filesystem，但很多老教程仍教用 moveTo()，这会导致远程驱动（如 OSS、Qiniu）直接报错或静默失败。
立即学习“PHP免费学习笔记（深入）”；
-
moveTo()只适用于local驱动；切换到qiniu或oss后，必须改用$file->store('images')或$file->storeAs('images', 'xxx.jpg') - 检查
config/filesystem.php中默认 disk 的'root'路径：它是相对public_path()的，不是ROOT_PATH；写成'root' => 'public/uploads'是错的，应为'root' => 'uploads' -
'url' => '/uploads'仅用于生成访问链接，不影响保存位置；但如果配错，前端拿到的 URL 会 404
大文件上传卡住或超时
上传几十 MB 文件时页面空白、502、408，往往不是 PHP 脚本超时（max_execution_time），而是 Nginx 接收阶段就断了。
-
client_body_timeout 300必须设大，它控制 Nginx 读取客户端上传数据的等待时间，慢网用户极易触发 408 -
fastcgi_read_timeout 300（PHP-FPM）或proxy_read_timeout 300（反向代理）也要同步调大，否则 Nginx 等不到 PHP 返回就关连接 - CDN、WAF、SLB 等中间件也有 body size 和 timeout 限制，必须一并检查，不能只调后端
- 生产环境不要硬扛单次大上传，分片上传（如使用
web-uploader或uppy）才是可靠方案
真正难排查的点往往藏在“看不见”的地方：SELinux/AppArmor 拦截、upload_tmp_dir 权限不对但没报错、Nginx client_max_body_size 写在了错误作用域、或者 filesystem.php 里 disk 配置和实际路径不匹配。建议每改一项就验证一项，别堆在一起调。
