thinkphp上传失败主因是表单enctype未设、name不匹配或nginx client_max_body_size限制；需先检查$_files，再用validate()校验并filesystem::disk()->putfile()保存，返回url须经disk配置拼接。
ThinkPHP上传文件失败，八成不是框架问题，而是表单编码、Nginx限制或校验逻辑没对上。直接用 request()->file() 拿不到文件？先别改代码，检查这三处：enctype 是否设对、name 是否和后端 key 一致、client_max_body_size 是否卡住了请求。
前端表单必须带 multipart/form-data 且 name 匹配
这是最常被忽略的底层前提。ThinkPHP 的 request()->file() 完全依赖 PHP 原生 $_FILES，而它只在 multipart/form-data 编码下才被填充。
-
<form method="post" enctype="multipart/form-data"></form>缺一不可；漏掉enctype，$_FILES就是空数组，后续所有操作都无效 -
<input type="file" name="avatar">的name必须和控制器里request()->file('avatar')的字符串完全一致（区分大小写） - Ajax 提交时，必须用
FormData构造，且不能手动设置Content-Type头——让浏览器自动加boundary，否则 Nginx 或 PHP 会拒收
后端要用 validate() + putFile()，别碰 moveTo()
$file->move() 是 ThinkPHP 5 的遗留用法，TP6 中它不处理重名、不兼容 OSS、不自动建目录，还容易因路径拼错静默失败。正确路径是走 Filesystem::disk() 驱动。
- 校验必须用
$file->validate(['size'=>2097152, 'ext'=>'jpg,png', 'type'=>'image/jpeg,image/png'])：type参数读文件头，防伪造；ext不区分大小写，但仅靠它不够安全 - 保存必须用
Filesystem::disk('public')->putFile('uploads', $file)：自动重命名、创建子目录、适配本地/云存储，返回的是相对路径如uploads/20260514/abc123.jpg - 别再用
$file->move('./public/uploads')——./在不同环境解析不稳定，且无法利用磁盘驱动的 visibility 和 URL 映射能力
Nginx 和 php.ini 的上传限制必须同步调大
上传中途断连、接口返回 500 但日志空白？大概率是某一层把请求截了，根本没进到 ThinkPHP。
- PHP 层：确认
php.ini中file_uploads = On，且upload_max_filesize和post_max_size都 ≥ 你预期的最大文件（例如10M），注意post_max_size必须 ≥upload_max_filesize - Nginx 层：检查
client_max_body_size，默认常为1m，需显式设为10M并 reload；若用多层代理（如 Nginx → Apache），还要确认中间层是否清空了Content-Length或重写了头 - 验证方法：在控制器开头加
dump($_FILES); exit;，如果数组为空或error === UPLOAD_ERR_INI_SIZE，就说明卡在了这里
返回给前端的 URL 不能拼接，得用 Url::build() 或 disk 配置的 url
上传成功后返回 /public/uploads/xxx.jpg？前端 404 是必然的。ThinkPHP 的 public 磁盘默认配置了 'url' => '/storage'，意味着真实可访问路径是 /storage/xxx.jpg，而不是物理路径。
- 如果用了
putFile('uploads', $file)，返回值是uploads/xxx.jpg，要拼上前缀：Url::build('/storage/' . $savename)，或者更稳妥地：用Filesystem::disk('public')->getTemporaryUrl()（本地磁盘下等价于拼/storage/） - 千万别返回
$file->getRealPath()或$info->getPathname()—— 这是服务器绝对路径，比如/var/www/html/runtime/storage/xxx.jpg，前端永远打不开 - 生产环境部署前，务必执行
php think storage:link，它会在public/storage下建软链接指向runtime/storage，确保 URL 路由能命中真实文件
真正难的不是写上传逻辑，而是理解 $_FILES 怎么来、Filesystem 磁盘怎么配、URL 路径怎么映射这三层关系。任何一个环节断开，都会导致“明明传了却没收到”“收到了却找不到”“找到了却打不开”。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
