本教程详细介绍了如何在 Laravel 应用中实现多文件上传功能。内容涵盖前端 Blade 模板中文件输入字段的正确命名方式（`name="field[]"`），以及后端控制器中如何接收、验证和遍历处理多个上传文件，并将其存储到指定磁盘，最终将每个文件路径与数据库记录关联，确保上传流程的完整性和正确性。
在现代 Web 应用中，用户上传文件是常见需求，而多文件上传更是提升用户体验的关键功能。然而，对于初学者来说，正确处理 Laravel 中的多文件上传可能会遇到一些挑战，尤其是在前端表单设置和后端控制器逻辑方面。本教程将深入探讨如何在 Laravel 中实现这一功能，从前端 Blade 模板的正确配置到后端控制器中文件的接收、验证和存储，提供一个全面且专业的解决方案。
1. 前端 Blade 模板配置
实现多文件上传的第一步是在前端表单中正确配置文件输入字段。关键在于 input 标签的 name 属性和表单的 enctype 属性。
1.1 表单 enctype 属性
所有包含文件上传的 HTML 表单都必须设置 enctype="multipart/form-data" 属性。这是浏览器告知服务器表单数据将以多部分形式编码的必需步骤，以便正确处理文件内容。
立即学习“前端免费学习笔记（深入）”；
<form method="POST" action="{{ route('storeLesson') }}" enctype="multipart/form-data">
<!-- 表单内容 -->
</form>1.2 input 标签的 name 属性
为了让 Laravel 识别并接收多个文件，input 标签的 name 属性必须以数组的形式命名，即在字段名后加上 []。例如，如果我们要上传多个“课程”文件，应使用 name="lessons[]"。这样，当表单提交时，request()->lessons 将会是一个包含所有上传文件对象的数组。
此外，为了实现每个文件对应一个课程，并且与特定的课程文件夹关联，我们可以调整 Blade 模板的结构。
修正后的 Blade 模板示例：
<form method="POST" action="{{ route('storeLesson') }}" enctype="multipart/form-data">
@csrf {{-- Laravel CSRF 保护 --}}
<div class="mb-3">
@foreach($course->lessonFolders as $folder)
<div class="card mb-2">
<div class="card-header">{{ $folder->name }}</div>
<div class="card-body">
{{-- 隐藏字段传递 lesson_folder_id --}}
<input type="hidden" name="lesson_folder_id" value="{{ $folder->id }}">
<label for="lessonFiles-{{ $folder->id }}" class="form-label">上传课程文件 (支持多选)</label>
{{-- 关键：使用 lessons[] 并添加 multiple 属性 --}}
<input name="lessons[]" type="file" class="form-control" id="lessonFiles-{{ $folder->id }}" multiple>
<div class="mt-2">
@foreach($folder->lessons as $lesson)
@if($lesson->lesson)
<span class="badge bg-success me-1">{{ basename($lesson->lesson) }}</span>
@endif
@endforeach
</div>
</div>
</div>
@endforeach
</div>
<button class="btn btn-danger" type="submit">上传</button>
</form>注意事项：
- name="lessons[]"：这是实现多文件上传的关键。
- multiple 属性：允许用户在文件选择对话框中选择多个文件。
- lesson_folder_id：这里假设一个表单提交只对应一个 lesson_folder_id。如果需要为不同文件夹上传文件，可能需要更复杂的表单结构或多次提交。在上述示例中，我们遍历了文件夹，但由于 name="lesson_folder_id" 是唯一的，最终提交的将是最后一个文件夹的 ID。更合理的做法是为每个文件夹单独一个上传表单，或者使用 JavaScript 动态处理。本教程将基于一个 lesson_folder_id 提交多个文件来演示。
2. 后端控制器处理逻辑
前端表单配置完成后，接下来需要在 Laravel 控制器中接收、验证和处理这些上传的文件。
2.1 请求验证
在处理文件之前，进行严格的验证至关重要，以确保文件符合预期类型、大小等要求，并防范潜在的安全风险。
- lessons 字段：由于前端使用了 name="lessons[]"，后端将接收到一个文件数组。因此，验证规则应针对数组及其每个元素。
- lessons.* 字段：这个通配符用于验证数组中的每一个文件。
use Illuminate\Http\Request;
use App\Models\Lesson; // 确保引入 Lesson 模型
class LessonController extends Controller
{
public function storeLesson(Request $request)
{
// 1. 验证请求数据
$validatedData = $request->validate([
'lesson_folder_id' => 'required|exists:lesson_folders,id', // 确保文件夹ID存在
'lessons' => 'required|array|min:1', // 必须上传至少一个文件
'lessons.*' => 'file|mimes:pdf,doc,docx,mp4,mov|max:20480', // 每个文件必须是指定类型且最大20MB
], [
'lesson_folder_id.required' => '请选择一个课程文件夹。',
'lesson_folder_id.exists' => '指定的课程文件夹不存在。',
'lessons.required' => '请上传至少一个课程文件。',
'lessons.array' => '上传的课程文件格式不正确。',
'lessons.min' => '请上传至少一个课程文件。',
'lessons.*.file' => '上传的不是有效文件。',
'lessons.*.mimes' => '文件类型不支持。支持PDF, DOC, DOCX, MP4, MOV。',
'lessons.*.max' => '单个文件大小不能超过20MB。',
]);
$lessonFolderId = $validatedData['lesson_folder_id'];
$uploadedFiles = $validatedData['lessons']; // 这是一个包含 UploadedFile 对象的数组
// 2. 遍历并存储每个文件
foreach ($uploadedFiles as $file) {
// 将文件存储到 'my_files' 磁盘下的 'lessons' 目录
// store() 方法会自动生成唯一文件名并返回相对路径
$path = $file->store('lessons', ['disk' => 'my_files']);
// 3. 为每个上传的文件创建新的 Lesson 记录
Lesson::create([
'lesson_folder_id' => $lessonFolderId,
'lesson' => $path, // 存储文件路径
'name' => $file->getClientOriginalName(), // 存储原始文件名，方便显示
// 根据实际需求添加其他字段
]);
}
return redirect('/courses')->with('success', '所有课程文件已成功上传。');
}
}2.2 文件迭代与存储
在验证通过后，$validatedData['lessons'] 将是一个 UploadedFile 对象的数组。我们可以通过 foreach 循环遍历这个数组，对每个文件执行存储操作。
$file->store('lessons', ['disk' => 'my_files'])：
- store() 方法是 Laravel 提供的便捷文件存储方式。
- 'lessons' 是文件在指定磁盘上的子目录。
- ['disk' => 'my_files'] 指定了要使用的文件系统磁盘。
2.3 数据模型关联
对于每个成功存储的文件，我们都会创建一个新的 Lesson 模型记录，将文件路径 ($path) 和对应的 lesson_folder_id 以及原始文件名存储到数据库中。这样，每个上传的文件都对应一个独立的课程记录。
3. 文件系统配置 (filesystem.php)
Laravel 的文件系统配置位于 config/filesystem.php。这里定义了各种存储磁盘，如本地存储、公共存储、S3 云存储等。本教程中使用了名为 my_files 的自定义磁盘。
config/filesystem.php 示例：
'disks' => [
'local' => [
'driver' => 'local',
'root' => storage_path('app'),
],
'public' => [
'driver' => 'local',
'root' => storage_path('app/public'),
'url' => env('APP_URL') . '/storage',
'visibility' => 'public',
],
's3' => [
'driver' => 's3',
'key' => env('AWS_ACCESS_KEY_ID'),
'secret' => env('AWS_SECRET_ACCESS_KEY'),
'region' => env('AWS_DEFAULT_REGION'),
'bucket' => env('AWS_BUCKET'),
'url' => env('AWS_URL'),
'endpoint' => env('AWS_ENDPOINT'),
'use_path_style_endpoint' => env('AWS_USE_PATH_STYLE_ENDPOINT', false),
],
'my_files' => [
'driver' => 'local',
'root' => public_path() . '/uploads' // 将文件存储到 public/uploads 目录下
]
],注意： 在上述示例中，为了将文件公开可访问，我将 my_files 的 root 路径修改为 public_path() . '/uploads'。这意味着上传的文件将直接存储在项目的 public/uploads 目录下，可以通过 URL 直接访问。如果希望文件不直接公开访问，应将其存储在 storage_path() 目录下，并通过控制器方法进行访问控制。
4. 最佳实践与注意事项
- 文件验证： 始终进行严格的文件验证，包括文件类型（mimes）、大小（max）、维度（dimensions for images）等，以防止恶意文件上传和服务器资源滥用。
- 错误处理： 在控制器中，如果验证失败，Laravel 会自动将错误信息重定向回前一个页面。在 Blade 模板中，可以使用 @error 指令显示这些错误信息，提升用户体验。
-
安全性：
- 文件名： 使用 store() 方法时，Laravel 会自动生成一个唯一的哈希文件名，这有助于避免文件名冲突和路径遍历攻击。避免直接使用用户提供的文件名。
- 文件内容： 对于可执行文件或脚本文件，即使存储在非 Web 可访问目录，也应谨慎处理。如果需要处理用户上传的图片，可以考虑使用图片处理库（如 Intervention Image）进行二次处理，去除潜在的恶意元数据。
- 权限： 确保存储文件的目录具有正确的写入权限，但不要赋予过高的权限。
-
数据库设计： 对于更复杂的媒体管理需求，例如一个课程可以有多个不同类型的文件（视频、PDF、PPT），或者一个文件可以属于多个实体，可以考虑以下方案：
- 多态关联： 使用 Laravel 的多态关联（Polymorphic Relations）创建一个通用的 Media 模型，与 Lesson 模型进行多态关联。
- JSON 字段： 如果文件数量不多且结构简单，可以将文件路径数组存储在一个 JSON 类型的数据库字段中。
- 进度条： 对于大文件或多个文件的上传，考虑使用 JavaScript 库实现上传进度条，提高用户反馈。
总结
通过本文的详细讲解，您应该已经掌握了在 Laravel 中实现多文件上传的核心技术。关键在于前端 input 标签的 name="field[]" 命名方式以及后端控制器中对文件数组的正确接收、验证和循环处理。结合 Laravel 强大的文件系统和验证功能，您可以构建出健壮且用户友好的文件上传系统。在实际开发中，请务必关注文件安全性和用户体验，并根据项目需求选择合适的数据库设计和文件存储策略。
