当前位置：首页 > 文章列表 > 文章 > php教程 > AJAX上传文件教程：FormData图片上传方法

AJAX上传文件教程：FormData图片上传方法

2026-03-14 21:36:29 0浏览收藏

本文手把手教你如何在 Laravel + jQuery 项目中正确实现 AJAX 图片上传，直击 CSRF 令牌缺失、FormData 构造错误和 AJAX 配置失当等高频痛点，明确指出必须将 FormData 实例作为 data 的唯一值传入、禁用 contentType 和 processData，并配合后端严谨的验证与安全存储逻辑，帮你彻底告别文件上传失败、419 错误或空文件到达后端的尴尬场景——无论你是上传航空公司 Logo 还是其他图片，这套经过实战验证的方案都能让你一次配置、稳定运行。

使用 AJAX 通过 FormData 正确上传文件（如图片）的完整教程

本文详解如何在 Laravel + jQuery 项目中，利用 AJAX 和 FormData 正确提交含文件（如 logo 图片）的表单，重点解决 CSRF 令牌缺失、FormData 构造错误、AJAX 配置不当导致文件无法到达后端的问题。

本文详解如何在 Laravel + jQuery 项目中，利用 AJAX 和 FormData 正确提交含文件（如 logo 图片）的表单，重点解决 CSRF 令牌缺失、FormData 构造错误、AJAX 配置不当导致文件无法到达后端的问题。

在 Web 开发中，通过 AJAX 异步提交带文件的表单（例如上传航空公司 Logo）是一个高频但易出错的需求。常见误区是试图将 FormData 对象与其他普通字段混合拼装进 data 对象中（如 { id, name, logo: formData }），这会导致文件数据被序列化丢失——FormData 必须作为整个 data 的唯一值传入，且不可与普通键值对混用。

✅ 正确实现步骤

1. 表单结构：确保 enctype 与 CSRF 令牌就位

Laravel 要求 POST 表单必须携带有效的 CSRF Token，否则请求会被中间件拦截。务必在

中添加 @csrf 指令，并保留 enctype="multipart/form-data"：

<form id="addEditBookForm" method="POST" enctype="multipart/form-data" action="{{ url('admin/add-update-Airlines') }}">
    @csrf
    &lt;input type=&quot;hidden&quot; name=&quot;id&quot; id=&quot;id&quot;&gt;
    <div class="form-group">
        <label class="col-sm-2 control-label">Name</label>
        <div class="col-sm-12">
            &lt;input type=&quot;text&quot; class=&quot;form-control&quot; name=&quot;name&quot; id=&quot;name&quot; required maxlength=&quot;50&quot;&gt;
        </div>
    </div>
    <div class="form-group">
        <label class="col-sm-2 control-label">Country</label>
        <div class="col-sm-12">
            &lt;input type=&quot;text&quot; class=&quot;form-control&quot; name=&quot;country&quot; id=&quot;country&quot; required maxlength=&quot;50&quot;&gt;
        </div>
    </div>
    <div class="form-group">
        <label class="col-sm-2 control-label">Logo</label>
        <div class="col-sm-12">
            &lt;input type=&quot;file&quot; class=&quot;form-control&quot; name=&quot;logo&quot; id=&quot;logo&quot; accept=&quot;image/*&quot; required&gt;
        </div>
    </div>
    <button type="submit" class="btn btn-primary" id="btn-save">Save changes</button>
</form>

⚠️ 注意：<input type="file"> 不支持 value 属性赋值（浏览器安全限制），请勿写 value=""；同时建议添加 accept="image/*" 提升用户体验。

2. AJAX 请求：直接传递 FormData 实例

关键点在于：

使用 new FormData(formElement) 构造完整表单数据；
data 字段只传 formData，不额外包裹其他字段（ID、name 等已包含在表单内）；
必须设置 contentType: false（禁用自动添加 Content-Type 头，让浏览器用边界符 boundary 自动设置）；
必须设置 processData: false（禁止 jQuery 将数据转为查询字符串）；
移除手动提取字段（如 $("#name").val()），避免冗余和不同步。

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

    const form = this;
    const formData = new FormData(form);

    $.ajax({
        type: 'POST',
        url: $(form).attr('action'),
        data: formData,
        contentType: false,   // 关键：不设置 Content-Type
        processData: false,   // 关键：不处理数据（保持原始 FormData）
        cache: false,
        dataType: 'json',
        beforeSend: function() {
            $('#btn-save').html('Submitting...').prop('disabled', true);
        },
        success: function(res) {
            Swal.fire('Success!', 'Airline saved successfully.', 'success');
            location.reload();
        },
        error: function(xhr) {
            const errors = xhr.responseJSON?.errors || {};
            Object.values(errors).forEach(msgs => msgs.forEach(msg => alert(msg)));
        }
    });
});

3. 后端控制器：验证与存储分离，增强健壮性

Laravel 中应先独立校验请求，再处理文件保存逻辑。注意：

mimes 规则中 ipg 应为 jpg（拼写错误）；
文件扩展名应通过 $request->logo->getClientOriginalExtension() 获取，而非 $request->logo->extension()（后者在部分环境下不可靠）；
建议使用 storeAs() 方法替代手动 move()，更符合 Laravel 最佳实践。

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

    // ✅ 安全获取并存储文件
    $fileName = time() . '-' . Str::slug($validated['name']) . '.' 
                . $request->logo->getClientOriginalExtension();
    $path = $request->logo->storeAs('public/img', $fileName);

    // ✅ 创建或更新模型（路径存相对路径，如 'img/xxx.png'）
    $airline = Airline::updateOrCreate(
        ['id' => $request->id],
        array_merge($validated, [
            'logo' => 'img/' . $fileName, // 存储路径，便于后续 URL 构建
        ])
    );

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

? 总结与注意事项

❌ 错误做法：data: { name: ..., logo: new FormData(...) } → FormData 被转为 [object FormData] 字符串；
✅ 正确做法：data: new FormData(form) → 浏览器原生处理二进制流；
CSRF 是前提：无 @csrf 或手动传 _token 字段均会 419 错误；
前端调试技巧：在 DevTools 的 Network → Payload 查看是否出现 ------WebKitFormBoundary... 及文件字段；
后端调试技巧：Log::info($request->all()); 可确认 logo 是否为 UploadedFile 实例；
安全提醒：始终校验 mimes 和 max，避免恶意文件上传。

遵循以上规范，即可稳定、安全地通过 AJAX 提交含图片的表单，适用于各类 Laravel 管理后台场景。

好了，本文到此结束，带大家了解了《AJAX上传文件教程：FormData图片上传方法》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！