FlaskAJAX文件上传失败解决办法

IT行业相对于一般传统行业，发展更新速度更快，一旦停止了学习，很快就会被行业所淘汰。所以我们需要踏踏实实的不断学习，精进自己的技术，尤其是初学者。今天golang学习网给大家整理了《Flask AJAX 上传文件失败解决方法》，聊聊，我们一起来看看吧！

在使用 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 <input type="file"> 元素本身添加到 FormData，而不是该元素所包含的实际文件对象。HTML 输入元素是一个 DOM 对象，而不是文件内容。

错误示例：

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

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

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

正确示例：

// 正确的做法：将 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'>
    &lt;input type=&apos;file&apos; id=&apos;image_field&apos; name=&quot;image&quot;&gt;
    <fieldset>
        <label for="title_en">Title EN:</label>
        &lt;input type=&quot;text&quot; id=&quot;title_en&quot; name=&quot;title_en&quot;&gt;
    </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)