Laravel 中使用 AJAX 上传文件（如图片）的完整实践指南

本文详解如何在 laravel 项目中通过 ajax 正确提交含文件（如 logo）的表单，重点解决 formdata 未生效、csrf 失败、后端接收不到文件等常见问题，并提供可直接运行的前后端完整代码。

本文详解如何在 laravel 项目中通过 ajax 正确提交含文件（如 logo）的表单，重点解决 formdata 未生效、csrf 失败、后端接收不到文件等常见问题，并提供可直接运行的前后端完整代码。

在 Laravel 开发中，使用 AJAX 提交带文件（如图片、PDF）的表单是一个高频但易出错的场景。许多开发者尝试用 FormData 构造数据并发送请求，却始终收不到文件——根本原因往往不是语法错误，而是请求配置缺失、CSRF 令牌未传递、或数据结构误用。下面我们将从 HTML 表单、JavaScript/AJAX 配置、到 Laravel 控制器三方面，系统梳理并实现一个健壮、可复用的文件上传流程。

✅ 正确构建支持文件上传的表单

首先，确保 <form> 标签满足以下三个关键条件：

• enctype="multipart/form-data"（必需，否则浏览器不会编码文件二进制流）
• 显式声明 method="POST"（Laravel 路由需匹配）
• 嵌入 CSRF Token（Laravel 默认校验，缺失将导致 419 错误）

<form id="addEditBookForm" method="POST" enctype="multipart/form-data">
    @csrf <!-- 关键：Laravel Blade 指令自动注入 _token 字段 -->
    <input type="hidden" name="id" id="id">

    <div class="form-group">
        <label>Name</label>
        <input type="text" name="name" id="name" class="form-control" required>
    </div>

    <div class="form-group">
        <label>Country</label>
        <input type="text" name="country" id="country" class="form-control" required>
    </div>

    <div class="form-group">
        <label>Logo (PNG/JPEG only)</label>
        <input type="file" name="logo" id="logo" class="form-control" accept="image/png,image/jpeg" required>
    </div>

    <button type="submit" class="btn btn-primary" id="btn-save">Save changes</button>
</form>

⚠️ 注意：不要给 type="file" 输入框设置 value 属性（无效），也不要手动 required="" —— HTML5 的 required 属性已足够。

✅ 使用 FormData 发送请求：正确姿势

核心原则：整个表单数据必须由 FormData 实例统一管理，且不能与普通 JSON 混合传参。你之前代码中将 id/name/country/logo 拆开赋值是错误的——FormData 对象无法被 JSON 序列化，且 logo: logo 这种写法会丢失文件元信息。

✅ 正确做法如下（兼容 jQuery）：

Joker AIx

一站式AI创意生产平台，覆盖图像、视频、音频、文案全品类创作

下载

$('#addEditBookForm').on('submit', function(e) {
    e.preventDefault();

    const form = this;
    const formData = new FormData(form); // ✅ 直接从表单 DOM 元素创建

    $.ajax({
        url: $(form).attr('action') || "{{ route('airlines.store') }}",
        type: 'POST',
        data: formData, // ✅ 整个 FormData 对象作为 data
        contentType: false, // ✅ 禁用 content-type，让浏览器自动设为 multipart/form-data
        processData: false, // ✅ 禁用处理（不序列化 FormData）
        cache: false,
        dataType: 'json',

        beforeSend: function() {
            $('#btn-save').prop('disabled', true).text('Uploading...');
        },

        success: function(res) {
            Swal.fire('Success!', 'Airline saved with logo.', 'success');
            location.reload(); // 或跳转/清空表单
        },

        error: function(xhr) {
            const errors = xhr.responseJSON?.errors || {};
            Object.entries(errors).forEach(([field, messages]) => {
                alert(`${field}: ${messages.join(', ')}`);
            });
        },

        complete: function() {
            $('#btn-save').prop('disabled', false).text('Save changes');
        }
    });
});

? 小贴士：使用 form.submit 事件比监听按钮点击更语义化，也避免重复绑定；$(form).attr('action') 可动态读取表单 action，提升可维护性。

✅ Laravel 后端：安全接收与存储文件

控制器中务必执行两步操作：先验证，再处理文件。切勿在 validate() 前访问 $request->logo，否则验证失败时可能抛出异常。

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Storage;

public function store(Request $request)
{
    // ✅ 第一步：集中验证（含文件规则）
    $validated = $request->validate([
        'name'    => ['required', 'string', 'max:255'],
        'country' => ['required', 'string', 'max:255'],
        'logo'    => ['required', 'file', 'mimes:jpeg,png,jpg', 'max:5120'], // 单位 KB
    ]);

    // ✅ 第二步：安全存储文件（推荐使用 Storage facade）
    $path = $request->file('logo')->store('airlines/logos', 'public'); // 存至 storage/app/public/airlines/logos/

    // ✅ 第三步：创建或更新模型（注意：logo 字段应存相对路径，如 'airlines/logos/xxx.png'）
    $airline = Airline::updateOrCreate(
        ['id' => $request->id],
        array_merge($validated, [
            'logo' => $path, // ✅ 存储路径，非原始 UploadedFile 对象
        ])
    );

    return response()->json(['success' => true, 'message' => 'Airline created successfully']);
}

? 提示：

• mimes:jpeg,png,jpg 比 ipg（明显拼写错误）更可靠；
• 使用 Storage::disk('public') 可生成可公开访问的 URL（需运行 php artisan storage:link）；
• 若数据库字段为 logo，建议类型设为 VARCHAR(255)，存储路径而非二进制内容。

? 补充：前端增强体验（可选）

• 添加文件预览：

  $('#logo').on('change', function() {
      const file = this.files[0];
      if (file && file.type.startsWith('image/')) {
          const reader = new FileReader();
          reader.onload = e => $('#preview').attr('src', e.target.result);
          reader.readAsDataURL(file);
      }
  });

• 限制文件大小前端提示（辅助验证）：

  if (this.files[0]?.size > 5 * 1024 * 1024) {
      alert('Logo must be under 5MB');
      return false;
  }

✅ 总结：关键检查清单

遵循以上规范，即可稳定实现 Laravel + AJAX 图片上传，兼顾安全性、可维护性与用户体验。