Laravel文件上传接口需严格对齐前后端约定：字段名（如avatar）须与HTML name属性完全一致且区分大小写；Content-Type必须为浏览器自动生成的multipart/form-data（Postman选form-data、前端用FormData不设header、curl用-F）；验证用required|file|mimes:jpg,png|max:2048；存储后调用Storage::url()返回可访问链接，前提已执行php artisan storage:link。
为 Laravel 文件上传接口写 Multipart 参数说明，核心是把“前端怎么发”和“后端怎么认”对齐，避免出现 request()->file('xxx') 返回 null 却找不到原因的情况。重点不在罗列字段，而在明确边界、约定细节、提示陷阱。
参数名与表单字段必须严格一致
文件字段的 key 名不是随意写的，它直接决定后端能否取到文件对象：
- HTML 表单中
<input type="file" name="avatar">→ 后端用$request->file('avatar') - 多文件上传写成
name="photos[]"→ 后端必须用$request->file('photos')获取数组，不能写'photos.0'或'photo' - 区分大小写和下划线：
avatar、Avatar、user_avatar是三个不同字段 - 调试建议：在控制器开头加
dd($request->allFiles())，直接看 PHP 原生接收到的文件结构
Content-Type 不用手动设置，但必须是 multipart/form-data
这是最常被文档忽略却导致 90% 上传失败的点。Multipart 请求的 Content-Type 必须带 boundary，而这个 boundary 只能由浏览器或客户端自动生成：
- Postman 中选 Body → form-data（不是 x-www-form-urlencoded，也不是 raw）
- 前端用
FormData时，绝对不要手动设置Content-Type头，否则会覆盖 boundary，Laravel 完全无法解析 - curl 测试必须用
-F "avatar=@/path/to/file.jpg"，不能用-d或--data-raw - API 文档里应注明：“本接口仅接受
multipart/form-data类型请求，客户端不可手动指定Content-Type”
验证规则要体现真实校验逻辑
文档里的 validation 规则不能只写“必填、2MB以内”，得说明它实际检查什么：
-
required|file：确保字段存在且是合法上传文件（绕过move_uploaded_file的安全检查） -
mimes:jpg,png,pdf：按文件内容魔数识别类型，不是看后缀名；.jpg文件若实际是 PNG，会校验失败 -
max:2048：单位是 KB，对应 PHP 的upload_max_filesize，需同步调大 Nginx 和 PHP 配置 - 建议组合使用：
'avatar' => 'required|file|mimes:jpeg,jpg,png|max:2048'
返回值说明要包含存储路径与可访问链接的生成方式
很多文档只写“返回文件路径”，但没说清楚这个路径是谁的、怎么变成 URL：
-
store('avatars')返回的是相对路径，如avatars/xyz123.jpg，属于storage/app/下 - 若用
public磁盘（推荐），需提前执行php artisan storage:link - 生成可访问链接应调用
Storage::url('avatars/xyz123.jpg')，返回类似/storage/avatars/xyz123.jpg - 文档中应注明：“返回路径为 Laravel 存储路径，非 Web 直接可访问地址；前端需拼接域名或通过后端提供完整 URL”
