Flask AJAX 文件上传指南：解决 request.files 为空的问题

在使用 Flask 配合 AJAX 进行文件上传时，开发者常遇到 `request.files` 对象为空的问题。本文旨在提供一份详细的教程，解析导致此问题的常见原因，并提供客户端（JavaScript `FormData` 和 jQuery `$.ajax` 配置）和服务器端（Flask `request.files` 处理）的正确实现方法，确保文件能够成功上传并被 Flask 应用正确接收。

Flask 与 AJAX 文件上传：常见问题与解决方案

在 Web 开发中，通过 AJAX 实现异步文件上传是提升用户体验的常见做法。然而，当使用 Flask 作为后端框架时，许多开发者会遇到 request.files 对象在服务器端接收到空 ImmutableMultiDict 的情况。这通常不是 Flask 本身的问题，而是客户端 JavaScript 代码在构建请求或发送请求时存在配置不当。

本教程将深入探讨导致 request.files 为空的两大主要原因，并提供详细的解决方案和示例代码。

1. 客户端 JavaScript FormData 构建不当

问题描述： 当尝试将文件添加到 FormData 对象时，一个常见的错误是直接将 HTML 元素本身添加到 FormData，而不是该元素所包含的实际文件对象。HTML 输入元素是一个 DOM 对象，而不是文件内容。

错误示例：

// 错误的做法：将整个 input 元素添加到 FormData
form_data.append("file", $("#edit_form #image_field")[0]);

上述代码会将 input 元素本身（或其字符串表示）添加到 FormData，而不是用户选择的文件。当服务器尝试解析时，它无法找到有效的文件流。

解决方案： 正确的做法是访问文件输入元素的 files 属性，它是一个 FileList 对象，包含了用户选择的所有文件。对于单文件上传，我们通常取第一个文件（files[0]）。

正确示例：

letterdrop

B2B内容营销自动化平台，从创意到产生潜在客户的内容的最佳实践和工具。

49

查看详情

// 正确的做法：将 input 元素中的第一个文件对象添加到 FormData
form_data.append("file", $("#edit_form #image_field")[0].files[0]);

通过 $("#edit_form #image_field")[0].files[0]，我们确保了添加到 FormData 的是一个实际的 File 对象，其中包含了文件的二进制数据。

2. jQuery $.ajax 配置不当

问题描述： 当使用 jQuery 的 $.ajax 方法发送包含 FormData 的请求时，必须正确配置 contentType 和 processData 这两个选项。如果配置不当，jQuery 可能会尝试对 FormData 对象进行不正确的处理，或者设置错误的 Content-Type 请求头，导致服务器无法正确解析文件数据。

错误示例：

$.ajax({
    type: 'POST',
    url: '/api/add_product_image',
    data: form_data,
    contentType: 'multipart/form-data', // 错误：jQuery 会尝试自行处理，并可能导致问题
    // processData 默认是 true，也会导致问题
    success: function(data) {
        console.log('Success!');
    },
});

当 FormData 对象被用作 data 参数时，浏览器会自动设置正确的 Content-Type（通常是 multipart/form-data 并带有正确的 boundary）。如果手动设置 contentType: 'multipart/form-data'，jQuery 可能会在 FormData 对象上执行额外的处理，并可能覆盖或损坏浏览器自动设置的 Content-Type 头，导致服务器无法解析。

processData 选项的默认值为 true，这意味着 jQuery 会尝试将 data 选项中的数据转换为查询字符串。对于 FormData 对象，这种行为是不正确的，因为它会破坏 FormData 对象的结构。

解决方案： 为了让浏览器能够正确处理 FormData 并设置正确的 Content-Type 头，同时防止 jQuery 对 FormData 进行不必要的处理，必须将 contentType 和 processData 都设置为 false。

正确示例：

$.ajax({
    type: 'POST',
    url: '/api/add_product_image',
    data: form_data,
    contentType: false,   // 关键：告诉 jQuery 不要设置 Content-Type 头
    processData: false,   // 关键：告诉 jQuery 不要处理数据
    success: function(data) {
        console.log('Success!');
    },
});

contentType: false 告诉 jQuery 不要设置 Content-Type 请求头，让浏览器自行处理 FormData 对象并设置正确的 multipart/form-data 头。 processData: false 告诉 jQuery 不要将 data 参数（即 FormData 对象）转换为字符串，而是直接发送原始数据。

3. Flask 服务器端处理

在 Flask 服务器端，接收文件相对直接，关键是使用 request.files 对象。

HTML 表单结构（仅供参考）： 虽然我们使用 AJAX，但了解原始 HTML 表单结构有助于理解 FormData 的构建和字段命名。

<form id="edit_form" action='' method='POST' enctype='multipart/form-data'>
    <input type='file' id='image_field' name="image">
    <fieldset>
        <label for="title_en">Title EN:</label>
        <input type="text" id="title_en" name="title_en">
    </fieldset>
    <!-- 其他字段 -->
</form>

请注意

from flask import Flask, request, jsonify
import os

app = Flask(__name__)

# 配置上传目录，确保该目录存在
UPLOAD_FOLDER = './static/imgs/'
if not os.path.exists(UPLOAD_FOLDER):
    os.makedirs(UPLOAD_FOLDER)

@app.route('/api/add_product_image', methods=['POST'])
def add_product_image():
    if request.method == 'POST':
        try:
            # 打印 request.form 和 request.files 以便调试
            print("Form Data:", request.form)
            print("Files Data:", request.files)

            # 从 FormData 中获取非文件字段
            product_id = request.form.get("id")
            if not product_id:
                return jsonify({"status": "error", "message": "Product ID is missing"}), 400

            # 从 request.files 中获取文件，注意这里的键 'file' 对应 JavaScript 中的 form_data.append("file", ...)
            file = request.files.get("file")

            if file and file.filename:
                # 构建安全的文件名
                filename = f"{product_id}_{file.filename}"
                # 确保文件名是安全的，避免路径遍历攻击
                from werkzeug.utils import secure_filename
                safe_filename = secure_filename(filename)

                # 保存文件到指定路径
                file_path = os.path.join(UPLOAD_FOLDER, safe_filename)
                file.save(file_path)
                return jsonify({"status": "success", "message": f"File saved as {safe_filename}"}), 200
            else:
                return jsonify({"status": "error", "message": "No file part or no selected file"}), 400

        except Exception as e:
            print(f"Error during file upload: {e}")
            return jsonify({"status": "error", "message": str(e)}), 500

if __name__ == '__main__':
    app.run(debug=True)

以上就是Flask AJAX 文件上传指南：解决 request.files 为空的问题的详细内容，更多请关注php中文网其它相关文章！