LaravelAPI怎么上传文件_Laravel处理文件上传接口【教程】-Laravel-PHP中文网

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。

laravelapi怎么上传文件_laravel处理文件上传接口【教程】

文件上传接口收不到 `$_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，交由前端拼完整地址