laravel文件上传失败返回500，主因是request()->file()未传字段名导致获取不到文件对象；须用request()->file('file')（匹配前端name属性），并确认enctype="multipart/form-data"、先调hasfile()判空、检查php上传限制。
检查 request()->file() 是否传了正确的字段名
上传失败却返回 500 或空响应，八成是因为控制器里没拿到文件对象。Laravel 的 request()->file() 必须带参数才能取到具体文件实例——不传参数它返回的是整个上传文件数组，不是单个 UploadedFile 对象。
常见错误写法：request()->file()（无参数）
正确写法：request()->file('file') 或 request()->file('document')，取决于你前端表单中 <input type="file" name="xxx"> 的 name 值。
- Dropzone 默认发的是
name="file"，所以得用request()->file('file') - 普通表单若写成
name="avatar"，就必须用request()->file('avatar') - 如果不确定字段名，可先 dump：
dd($request->allFiles())看实际键名
确认 enctype="multipart/form-data" 是否漏写
这是最隐蔽也最常被忽略的一环。没有这个属性，浏览器根本不会把文件内容发给后端，request()->file() 永远为空，且不会报错，只默默丢弃文件字段。
检查你的表单标签是否完整包含该属性：
- Blade 中漏掉
@csrf会导致 419 错误，但和上传失败无关；而漏掉enctype才真让上传“静默失效” - 使用 API 方式（如 Axios）上传时，必须手动设置
Content-Type为multipart/form-data，且不能显式设值（应让浏览器自动生成 boundary）
验证 $request->hasFile() 再调用 move() 或 store()
直接对可能为空的 $request->file('xxx') 调用方法，会触发 PHP 致命错误（Call to a member function on null），直接 500。必须先判断存在性。
- 错误示范：
$request->file('file')->store('uploads')（没判空） - 正确顺序：
if ($request->hasFile('file')) { ... } - 更稳妥的做法是配合 validate：
$request->validate(['file' => 'required|file|mimes:jpg,png,pdf|max:2048'])，它会在进入逻辑前拦截非法请求
留意 php.ini 的上传限制是否生效
即使 Laravel 代码完全正确，upload_max_filesize、post_max_size 或 max_execution_time 过小也会导致上传中途断开，现象是 Nginx/Apache 返回 500 或 413，Laravel 根本收不到请求。
- 检查当前配置：
php -i | grep -E "upload_max_filesize|post_max_size|max_execution_time" - 常见坑：
post_max_size必须 ≥upload_max_filesize，否则大文件连 POST 数据都收不全 - Laravel 日志里通常看不到这类错误，需查 Web 服务器错误日志（如
/var/log/nginx/error.log）
