Laravel API 文件上传失败主因是请求未用 multipart/form-data：Postman 须选 form-data、curl 用 -F、前端用 FormData 且不手动设 Content-Type；Nginx 的 client_max_body_size、PHP 的 upload_max_filesize 和 post_max_size 需同步配置；验证用 request()->validate()，存储用 store() 或 storeAs()，返回 URL 前确保已执行 php artisan storage:link。
文件上传接口收不到 $_FILES？检查请求是否用了 multipart/form-data
Laravel API 默认不解析 multipart/form-data 请求体，尤其是用 Postman、curl 或前端 fetch 发送时，如果漏设 Content-Type 或直接传 JSON，request()->file() 会返回 null，连 $_FILES 都为空。
- Postman 中必须手动选 “form-data” 类型（不是 “x-www-form-urlencoded” 或 raw）
- curl 要加
-F "file=@/path/to/file.jpg"，不要用-d或--data-raw - 前端用
FormData构造请求，且不能手动设置Content-Type头——浏览器会自动加带 boundary 的multipart/form-data；手设了反而会破坏解析 - Laravel 10+ 在 API 路由中默认禁用
session和csrf，但不影响文件上传；不过如果混用了web中间件，可能触发 CSRF 校验失败，报419 Page Expired
request()->file('avatar') 返回 null 的 3 种真实原因
不是代码写错了，而是上传链路上某处断了。常见于字段名不一致、Nginx 限制、或 Laravel 配置未生效。
- 前端
FormData.append('avatar', file)和后端request()->file('avatar')的键名必须完全一致（区分大小写），别写成'Avatar'或'file' - Nginx 默认限制上传大小：
client_max_body_size 10M;，超出则整个请求被截断，Laravel 根本收不到任何数据——查 Nginx error log 里有没有413 Request Entity Too Large -
php.ini中的file_uploads = On、upload_max_filesize = 10M、post_max_size = 12M必须同时满足，且重启 PHP-FPM；只改 Laravel 的validation规则没用
验证 + 存储一步到位：别在控制器里手动调 move_uploaded_file
Laravel 的 UploadedFile 对象封装了安全校验和移动逻辑，自己用 move_uploaded_file 不仅绕过 MIME 检查，还容易写错路径、权限失控。
Laravel Cloud
下载
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- 用
$request->validate(['avatar' => 'required|image|mimes:jpg,png|max:2048'])先校验，它会自动调用getMimeType()和isValid()，比前端 JS 校验可靠得多 - 存储推荐用
$request->file('avatar')->store('avatars', 'public')，而不是->move(...)；前者走 Flysystem 抽象层，支持本地、S3、SFTP 等驱动，且自动处理目录创建和唯一文件名 - 如果要自定义文件名，用
storeAs('avatars', 'user_'.$id.'.'.$request->file('avatar')->extension(), 'public')，别拼字符串——extension()比getClientOriginalExtension()更安全（防伪造）
API 返回文件 URL 时，Storage::url() 为什么 404？
开发环境常踩这个坑：本地用 public 盘存文件，但没配好符号链接或 Web 服务器路由，导致生成的 URL 实际不可访问。
-
php artisan storage:link必须运行（且确保public/storage是软链到storage/app/public），否则Storage::url()返回的路径在 Nginx/Apache 下 404 - 如果用的是
local驱动但想让 URL 可访问，盘配置里'url' => env('APP_URL').'/storage'要对应 Web 服务器能映射到public/storage的路径 - API 不该返回
file://或绝对磁盘路径——哪怕你本地测试能打开，生产环境肯定炸；只返回相对 URL，交由前端拼完整地址
上传路径权限、Nginx 的 client_max_body_size、以及 storage:link 是否真生效——这三个点不逐个确认，光调 Laravel 方法没用。
