laravel文件上传失败90%因表单或配置错误：form缺enctype="multipart/form-data"必返回null；name属性须与request()->file()参数完全一致；store()自动生成哈希名，storeas()需手动拼扩展名；验证用mimetypes+extensions组合更安全；大文件需同步调大php和nginx上传限制；公开访问须用public磁盘并执行storage:link。
直接说结论：Laravel 文件上传失败，90% 是表单或配置没写对，不是代码逻辑问题；request()->file() 返回 null 时，别急着改控制器，先看 HTML 和 PHP 底层限制。
form 没加 enctype="multipart/form-data" 就一定会 null
这是最常踩的坑。浏览器根本不会把文件数据打包进请求体，$_FILES 为空，Laravel 自然拿不到 UploadedFile 实例。
-
<form method="POST"></form>→ 必定null，无论后端怎么写 -
<form method="POST" enctype="multipart/form-data"></form>→ 才可能成功 -
<input type="file" name="avatar">的name值，必须和request()->file('avatar')中的字符串**完全一致**（大小写、下划线都不能错） - 如果用数组上传：
name="photos[]"，那得用request()->file('photos')拿到数组，不能写file('photos.0') - 临时验证是否真传过来了：在控制器开头加
dd(request()->allFiles())，直接看原始$_FILES内容
store() 和 storeAs() 到底怎么选
两者都走默认磁盘（通常是 local），但控制粒度不同，混用容易路径错乱或覆盖已有文件。
-
$file->store('avatars')→ 自动生成哈希名，存进storage/app/avatars/，适合头像、附件等无需语义化命名的场景 -
$file->storeAs('avatars', 'user_'.$id.'.'.$file->getClientOriginalExtension())→ 路径+名字全由你定，但必须手动拼扩展名，不能直接用getClientOriginalName()（含恶意路径如../.env） - 想让文件能被 Web 直接访问（比如
/storage/avatars/xxx.jpg），必须用public磁盘，并提前运行php artisan storage:link - 别在
storeAs()里硬塞用户原名，先过滤：用str($file->getClientOriginalName())->slug()或uniqid()+getClientOriginalExtension()
验证规则为什么总不生效
mimes:jpg,png 看似简单，实际依赖服务器的 fileinfo 扩展和 MIME 映射表，不是靠后缀名判断的——用户把 shell.php 改成 shell.jpg，照样可能通过校验。
-
mimes校验的是$_FILES['x']['type']字段，这个值由浏览器发送，**完全可伪造** - 真正安全的是
mimetypes:image/jpeg,image/png，它读文件头（magic bytes），但要求 PHP 开启finfo扩展 - 更稳妥的做法是组合：
'avatar' => 'required|image|mimetypes:image/jpeg,image/png|extensions:jpg,jpeg,png|max:2048'（extensions是 Laravel 9+ 内置规则） -
max:2048单位是 KB，不是 MB；且 PHP 配置upload_max_filesize和post_max_size必须 ≥ 这个值，否则请求在进 Laravel 前就被 Nginx/Apache 拦截，连 413 都看不到 - 大文件上传失败报 500 或空白页？大概率是本地开发环境 PHP 配置宽松，上线后没同步调大
upload_max_filesize和 Nginx 的client_max_body_size
上传后图片没法访问或显示异常
文件确实存进去了，但 URL 打不开、图片损坏、中文名乱码，这些问题基本都出在路径、磁盘配置或元数据处理上。
- 用
Storage::url()生成 URL，不要手动拼/storage/xxx；它会根据APP_URL和磁盘配置自动补前缀 - 确认
config/filesystems.php中public磁盘的root指向storage_path('app/public')，visibility是'public' - Laravel 不处理图片压缩、EXIF 清理、尺寸裁剪——上传后直接返回原始文件 URL，等于把潜在恶意元数据暴露出去
- 生产环境必须用
intervention/image等包二次处理：先move()到临时位置，再Image::make()读取、调整、保存，最后删临时文件 - 中文文件名在某些 Nginx + PHP-FPM 组合下会 502，建议统一转拼音或哈希前缀，别依赖原名
最易被忽略的一点：所有 store* 方法默认存在 storage/app/ 下，而这个目录**不可 Web 访问**；想公开访问，必须走 public 磁盘 + storage:link，且不能只配磁盘不跑命令。
