Laravel不直接处理文件，上传成败取决于表单配置、中间件限制、存储驱动及store()/move()调用方式；需确保enctype="multipart/form-data"、正确验证、安全处理扩展名与图片元数据，并配置PHP/Nginx底层参数。
Laravel 本身不直接“处理文件”，它只负责接收 Illuminate\Http\UploadedFile 实例并提供统一接口；真正决定上传成败的，是表单配置、中间件限制、存储驱动配置和你调用的 store() 或 move() 方式。
确保表单和请求能正确提交文件
常见错误是表单漏掉 enctype="multipart/form-data"，导致 $request->file('avatar') 永远为 null；另外，Laravel 默认的 VerifyCsrfToken 中间件不会拦截文件上传，但如果你用了自定义中间件或 API 路由，需确认未误删 Accept 或 Content-Type 头。
- HTML 表单必须带
enctype="multipart/form-data" - Laravel 控制器中用
$request->file('field_name')获取实例，不是$request->input() - 验证规则必须显式加
'image'、'mimes:jpeg,png'或'max:2048'，否则大文件会静默失败（实际卡在 PHP 的upload_max_filesize）
store() 和 storeAs() 的区别与选型
store() 自动生成唯一哈希名并存入默认磁盘（通常是 public），适合无需保留原文件名的场景；storeAs() 允许你指定路径和文件名，但需自行处理重名、扩展名校验和安全过滤——比如用户传 shell.php.jpg，你若直接用原名保存就可能埋下隐患。
【极品模板】出品的一款功能强大、安全性高、调用简单、扩展灵活的响应式多语言企业网站管理系统。 产品主要功能如下： 01、支持多语言扩展（独立内容表，可一键复制中文版数据） 02、支持一键修改后台路径； 03、杜绝常见弱口令，内置多种参数过滤、有效防范常见XSS； 04、支持文件分片上传功能，实现大文件轻松上传； 05、支持一键获取微信公众号文章（保存文章的图片到本地服务器）； 06、支持一键
-
$request->file('photo')->store('avatars')→ 返回类似avatars/9a2b3c4d.jpg -
$request->file('photo')->storeAs('avatars', 'user_123.jpg')→ 强制存为该路径+名字 - 若用
storeAs()，务必用$request->file('photo')->getClientOriginalExtension()取扩展名，别信getClientOriginalName()里的完整字符串 - 所有
store*方法底层调用的是当前默认磁盘（config/filesystems.php中default配置），不是硬编码public_path()
图片缩略图与安全处理必须手动做
Laravel 不内置图片压缩、裁剪或 EXIF 清理。上传后直接 store() 并返回 URL，等于把原始文件（含潜在恶意元数据）暴露给 Web 访问。生产环境必须用第三方包如 intervention/image 做二次处理。
- 安装：
composer require intervention/image - 处理示例：先
move()到临时目录，再用Image::make()读取、调整尺寸、保存，最后删临时文件 - 不要跳过扩展名验证：即使 MIME 类型是
image/jpeg，也得用getimagesize()或Image::make()实际打开一次，防止伪造头 - 公开可访问的图片路径（如
/storage/avatars/xxx.jpg）必须通过php artisan storage:link符号链接到public/storage，不能直接写public_path()硬路径
use Illuminate\Http\Request;
use Intervention\Image\Facades\Image;
public function upload(Request $request)
{
$request->validate([
'avatar' => 'required|image|mimes:jpeg,png,jpg,gif|max:2048',
]);
$file = $request->file('avatar');
$filename = 'user_' . auth()->id() . '_' . time() . '.' . $file->getClientOriginalExtension();
// 先存临时
$tempPath = $file->storeAs('temp', $filename, ['disk' => 'local']);
// 用 Intervention 处理
$img = Image::make(storage_path('app/' . $tempPath));
$img->resize(300, null, function ($constraint) {
$constraint->aspectRatio();
});
$img->save(storage_path('app/avatars/' . $filename));
// 清理临时文件
\Storage::disk('local')->delete($tempPath);
return response()->json(['path' => 'avatars/' . $filename]);
}
真正容易被忽略的点：PHP 的 post_max_size 和 max_execution_time 会比 Laravel 验证更早截断请求；Nginx 还要额外配 client_max_body_size。这些不在 Laravel 代码里，但任一没调都会让上传在框架外就失败。
