前端多文件上传时name属性必须为name="files[]"且input需添加multiple属性,同时表单enctype必须为multipart/form-data,否则后端无法获取文件数组。

前端表单 name 属性必须写成 name="files[]"
这是最常踩的坑:很多人照着单文件写成 name="file" 或 name="files",结果后端 $request->file('files') 拿到的是 null 或单个文件对象,根本不是数组。
关键就一条:multiple 属性 + 方括号语法 缺一不可:
-
✅ -
❌(Laravel 不识别为数组) -
❌(没加multiple,用户只能选 1 个,但后端仍按数组处理,容易空指针)
另外别漏掉 enctype="multipart/form-data",否则整个 $_FILES 是空的,$request->file() 必然返回 null。
$request->file('files') 返回的是 UploadedFile 对象数组,不是普通数组
它看起来像数组,但每个元素是 Illuminate\Http\UploadedFile 实例,有自己的一套方法链。直接 print_r 或 dd 容易误判结构。
实操建议:
- 先用
is_array($request->file('files'))或count($request->file('files'))确认非空 - 遍历时别用
foreach ($request->file('files') as $file)就完事——得立刻验证每个$file是否有效:if (!$file || !$file->isValid()) continue; - 验证规则要写成
'files.*' => 'required|file|mimes:jpg,png,pdf|max:5120',.*才能命中每个元素
存储时别在循环里反复调用 store() 而不控制路径和命名
默认 $file->store('uploads') 会为每个文件生成随机哈希名,存进同一目录。上传 100 张图?全挤在 storage/app/uploads/ 下,后期根本没法查、没法清理。
Laravel Cloud(cloud.laravel.com)。此技能用于处理所有 Laravel Cloud 请求,包括搜索和读取数据。只要任务涉及 Laravel Cloud,即使用此技能。
更稳妥的做法:
- 用
$file->storeAs("uploads/{$userId}/" . uniqid(), $file->getClientOriginalName())分用户隔离 - 或统一用
Storage::putFile("uploads/{$userId}", $file),由 Laravel 自动处理命名 - 如果需要保留原始名且防冲突,先
$originalName = pathinfo($file->getClientOriginalName(), PATHINFO_FILENAME),再拼上时间戳或哈希
注意:storeAs() 第二个参数是「完整文件名」,包含扩展名;而 getClientOriginalName() 已含扩展名,别重复加 .png。
大文件或多文件并发上传时,别忽略 PHP 和 Nginx 的底层限制
前端看着能选 20 个 50MB 的视频,后端却只收到 3 个——大概率是被拦在网关或 PHP 层了。
必须核对三处配置:
- Nginx:
client_max_body_size 200M(改完 reload) - PHP
php.ini:upload_max_filesize = 100M、post_max_size = 200M、max_execution_time = 300(上传耗时长,别卡 30 秒) - Laravel 验证层:
max:204800这种数值单位是 KB,别写成max:200当成 MB
真正难调试的点在于:这些限制失败时,Laravel 往往收不到请求体,$request->file() 是空的,日志里也不报错——只能靠抓包或看 Nginx error log 确认是否被截断。










