文件上传接口收不到$_FILES，先确认Content-Type是否为multipart/form-data；Laravel依赖PHP原生$_FILES，仅在此类型下填充，Postman选form-data、axios用FormData且不设Content-Type；路由需为POST/PUT/PATCH，避免中间件提前读取body；storeAs()推荐使用，move()绕过Flysystem不兼容S3；验证需字段名一致、含file规则、mimes按内容非后缀匹配；413错误需同步调大PHP、Nginx、Apache三层限制。
文件上传接口收不到 $_FILES？先确认是否用了 multipart/form-data
Laravel 的文件上传完全依赖 PHP 原生的 $_FILES，而它只在请求 Content-Type 是 multipart/form-data 时才被填充。用 Postman 或 axios 测试时，默认是 application/json，这时候 $request->file('avatar') 永远返回 null，不是 Laravel 问题，是 HTTP 协议层就断了。
- Postman 中：Body → form-data，别选 raw
- axios 中：
FormData实例直接传，别JSON.stringify；header 别手动设Content-Type，让浏览器自动带 - Laravel 路由必须用
POST（或PUT/PATCH），且中间件不能干扰上传流（比如某些自定义日志中间件会提前读取 body）
storeAs() 和 move() 别混用：一个走 Flysystem，一个直操作磁盘
$request->file('photo')->storeAs('avatars', 'user_123.jpg') 是推荐写法，它走 Laravel 的存储抽象层，自动适配本地、S3 等驱动；而 $request->file('photo')->move($path, $name) 是绕过 Flysystem 直接调 move_uploaded_file()，一旦你切到 S3 就彻底失效。
-
storeAs()返回的是相对路径（如avatars/user_123.jpg），不是完整 URL，要生成可访问链接得配合Storage::url() - 如果强制用
move()，记得检查目标目录权限和upload_max_filesize（PHP 配置），Laravel 不管这些底层限制 - 上传大文件时，
storeAs()默认会把文件先写入临时目录再移动，比move()多一次 IO，但安全可控
验证失败却没报错？检查 required|file|mimes:jpg,png 的顺序和字段名
Laravel 验证器对文件字段很敏感：如果字段名拼错、没加 file 规则、或者 mimes 对应的 MIME 类型不匹配（比如前端传了 .jpg 但实际内容是 PNG），都会静默失败——$request->validated() 可能空数组，$request->file() 是 null，但验证器不抛异常。
Laravel Cloud
下载
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- 表单字段名必须和验证规则里的一致，比如规则写
'avatar' => 'required|file'，HTML input 的name就得是avatar，不是photo或image -
mimes检查的是文件内容魔数，不是后缀名；.jpg 文件若被重命名为 .png，mimes:png仍会失败 - 调试时加一句
dd($request->allFiles(), $request->validator->errors())，看文件是否进来、错误信息在哪条规则
API 接口返回 413 Request Entity Too Large？不只是 Laravel 的锅
上传大文件报 413，第一反应常是改 Laravel 的 php.ini，但 Nginx/Apache 也有独立限制，三者必须同时调大：
- PHP：
upload_max_filesize和post_max_size（后者需 ≥ 前者） - Nginx：
client_max_body_size 20M（加在 server 或 location 块） - Apache：
LimitRequestBody 20971520（单位字节） - Laravel 自身无上传大小限制，它只读 PHP 提供的
$_FILES，所以 PHP 层拦住就到不了 Laravel
改完记得重启对应服务，光 reload PHP-FPM 不够。
