表单文件上传报错需分层定位：先确认HTML表单含enctype="multipart/form-data"且name一致；再检查PHP配置（file_uploads、upload_max_filesize等）及Web服务器限制（如Nginx的client_max_body_size）；最后排查验证规则、存储权限及API场景下Content-Type与$request->all()误用问题。
表单带文件的 POST 请求报错，不能笼统归为“后端错了”，得拆开看是哪一环断了。Laravel 本身不拦截文件上传，但中间任何一环配置不对，都会导致 $request->file() 返回 null、500 空响应，或提示“未知错误”。关键不是“单独处理上传”，而是分层定位、分步修复。
先确认表单和请求是否真正发出了文件
这是最常被跳过的一步。很多报错其实根本没走到 Laravel 控制器里。
- HTML 表单必须显式写
enctype="multipart/form-data"，缺了这一句，浏览器会把 file 字段当普通文本丢弃，$request->file('xxx')必然为 null -
<input type="file" name="avatar">的name值，必须和控制器里$request->file('avatar')的字符串完全一致（区分大小写、空格） - 如果用了数组上传（如
name="photos[]"），$request->file('photos')返回的是数组，不能直接调用->store()，要遍历处理 - Blade 中误加
@method('POST')（尤其在本就是 POST 路由时）可能干扰提交逻辑，删掉只留@csrf即可
检查 PHP 和 Web 服务器是否接收到了文件
如果 $_FILES 为空，说明请求压根没进 PHP，问题出在底层配置。
- 运行
php -i | grep -E "(upload_max_filesize|post_max_size|file_uploads)"查 CLI-FPM 实际值，别只信 phpinfo() 页面 - Nginx 用户必须设置
client_max_body_size，且值要大于post_max_size，否则请求在进 PHP 前就被截断 - Apache 若启用了 mod_security，它可能静默拦截 multipart 请求，临时禁用可验证是否是它“背锅”
- 确保
file_uploads = On，这个开关关了，所有上传都失效
验证和存储环节的典型陷阱
即使文件进了控制器，也容易在验证或保存时失败，且错误不明显。
- 验证规则必须显式写，比如
'avatar' => 'required|image|mimes:jpeg,png|max:2048'；没写required或image，大文件会在 PHP 层静默丢弃，而不是抛 Laravel 验证异常 -
store()默认存到storage/app下，依赖该目录有写权限；部署时经常漏设storage/app和bootstrap/cache权限 - 用
storeAs()保留原名时，别直接传$file->getClientOriginalName()——用户可能传../../.env这类路径，应只取扩展名：uniqid().'.'.$file->getClientOriginalExtension() - 图片类文件务必二次校验：MIME 类型可伪造，要用
getimagesize()或 Intervention/Image 打开一次确认真实类型
API 场景下的特殊注意事项
如果是 API 路由（如 routes/api.php），默认不启用 CSRF 验证，但其他限制更严格。
- API 路由默认无
VerifyCsrfToken中间件，但若你手动加了，需确认未误删Accept或Content-Type头 - 前端发请求时，
Content-Type不能手动设为application/json—— 文件上传必须让浏览器自动设为multipart/form-data，否则 Laravel 解析失败 - 不要在中间件或控制器早期调用
$request->all()或$request->input()，这会触发 Laravel 提前解析全部输入，导致后续$request->file()返回 null（PHP 的$_FILES只能读一次）
