Python requests发送multipart/form-data:文件与字段混合提交教程

Noah
Noah
发布时间:2026-11-16 | 5人浏览过
原创

本文详细介绍如何使用Python requests库发送multipart/form-data请求,实现文件与普通表单字段的混合提交。包含标准语法、进阶元数据设置、常见报错排查及完整代码示例。

在使用 Python 编写网络客户端或调用 Web API 时,经常需要同时提交普通表单字段(如用户ID、文件描述、授权标识)与二进制文件(如文档、图片、压缩包)。本文直接剖析 requests 库处理 multipart/form-data 的核心机制,提供标准混合提交范例、自定义文件元数据技巧,并重点说明容易导致请求解析失败的关键排错细节。

一、理解 multipart/form-data 的报文结构与参数映射

在标准的 HTTP POST 交互中,如果只提交纯文本键值对,通常使用 application/x-www-form-urlencoded;如果只提交纯二进制流,则通常使用裸数据流或 JSON。但当请求中既包含常规文本字段又包含文件内容时,HTTP 协议规范要求使用 multipart/form-data 编码。

这种编码方式会将整个请求体划分为多个互相独立的“分块”(Part),每个分块由一个随机生成的边界字符串(Boundary)隔开。每个分块拥有独立的 Content-Disposition 和可选的 Content-Type 描述头:

  • 普通字段分块:仅需声明 name="field_name",下方紧随具体的文本内容。
  • 文件分块:额外包含 filename="example.ext" 以及该文件对应的 MIME 类型(如 image/png),下方则是二进制字节流。

在 Python requests 库中,构建这种混合请求的核心就在于同时使用 data 参数传递普通键值,以及使用 files 参数传递文件对象。

Python requests发送multipart/form-data:文件与字段混合提交教程
图 1:Python 参数到 HTTP multipart 报文分块的结构映射关系

二、基础实战:同时提交文本字段与单个文件

在进行混合提交时,最稳健的做法是将纯文本参数放入一个字典赋值给 data,并将以二进制模式打开的文件对象包装进字典赋值给 files。

Python requests发送multipart/form-data:文件与字段混合提交教程
图 2:混合提交的标准四步操作流程

完整基础代码示例

以下是在实际工程中最常用的标准写法。请务必使用 with open(...) 结构打开文件,确保在请求发送完毕(或发生网络异常退出)后,文件句柄能够被操作系统正常释放。

import requests

url = "https://httpbin.org/post"

# 1. 普通表单字段(标量数据)
form_data = {
    "user_id": "9527",
    "category": "contract",
    "is_urgent": "true"
}

# 2. 文件字段:二进制只读模式 'rb'
file_path = "sample_contract.pdf"

try:
    with open(file_path, "rb") as file_handle:
        # files 字典的 key 对应后端接收字段的名称
        files_payload = {
            "attachment": file_handle
        }

        # 3. 发送混合 POST 请求
        # 注意:不要在此处手动设置 headers={'Content-Type': 'multipart/form-data'}
        response = requests.post(url, data=form_data, files=files_payload, timeout=30)

    # 4. 检查与处理返回
    response.raise_for_status()
    print("上传成功,服务器响应:", response.json())

except FileNotFoundError:
    print(f"本地错误:未找到目标文件 {file_path}")
except requests.exceptions.RequestException as err:
    print(f"网络或请求异常:{err}")
关键细节:为什么文件必须以 'rb' 二进制模式读取?

如果以默认的 'r' 文本模式打开,Python 会尝试根据系统编码(如 UTF-8 或 GBK)对字节进行解码和换行符替换。遇到 PDF、ZIP、PNG 等非文本文件时,不仅会触发解码报错,还会破坏原本的二进制文件内容。二进制模式 'rb' 能保证字节原样传输。

三、进阶用法:自定义文件名、MIME 类型与多文件上传

在很多业务场景中,我们可能并不希望后端接收到本地磁盘上的真实文件名(如包含了本地绝对路径或敏感信息),或者后端框架(如 Spring Boot、Django、FastAPI)严格校验了文件的 Content-Type,若未能正确识别则会拒绝处理。

1. 自定义文件元数据(使用元组结构)

在 files 字典中,每个字段对应的值除了可以直接是文件对象外,还可以是一个包含 2 到 4 个元素的元组。其标准格式如下:

# 格式:(filename, fileobj, [content_type, [custom_headers]])
files = {
    'upload_field': ('custom_filename.png', open('local.tmp', 'rb'), 'image/png')
}
元组位置 元素含义 示例值 说明
索引 0 发送给服务端的虚拟文件名 "report_2026.xlsx" 若传 None,则该分块不生成 filename 属性(可用于模拟普通字段)
索引 1 文件内容或文件对象 file_obj 或 b"..." 支持已打开的二进制流、io.BytesIO 内存流或原生 bytes
索引 2(可选) 文件的 MIME 类型 "application/pdf" 若省略,requests 会尝试根据文件名后缀自动推断
索引 3(可选) 专属于该分块的额外 HTTP 头 {"X-File-MD5": "..."} 通常极少用到,仅在特定私有协议下配置

2. 混合上传多个文件

如果表单支持同时上传多个文件,分为两种情形:

  • 不同字段名对应不同文件:直接在 files 字典中添加不同的键即可,例如 {'avatar': f1, 'id_card': f2}。
  • 同一个字段名接收多个文件:不能使用字典(因为字典键唯一),而应将 files 定义为一个包含双元组的列表。
# 同一字段名上传多文件的标准列表语法
multiple_files = [
    ('documents', ('doc1.pdf', open('file1.pdf', 'rb'), 'application/pdf')),
    ('documents', ('doc2.pdf', open('file2.pdf', 'rb'), 'application/pdf'))
]

form_data = {'batch_title': '2026年第一季度报表'}

response = requests.post(
    "https://httpbin.org/post",
    data=form_data,
    files=multiple_files
)

四、常见陷阱与避坑指南:为什么绝对不要手动指定 Content-Type

初学者最常犯的错误,就是通过 headers={'Content-Type': 'multipart/form-data'} 显式指定请求头。这种操作会直接导致服务器解析请求体失败(常见表现为 HTTP 400 Bad Request、Missing boundary 参数或后端获取到的所有字段与文件均为空)。

Python requests发送multipart/form-data:文件与字段混合提交教程
图 3:显式设置与自动生成 Content-Type 的核心差异
原理解释:Boundary(边界符)的作用

multipart/form-data 报文中,必须依靠一串不会在正文中重复出现的边界标识符(如 ----WebKitFormBoundary7MA4YWxkTrZu0gW)来区分“字段 A 结束”、“文件开始”、“文件结束”。 当 requests 检测到传入了 files 参数时,它会自动在底层计算随机边界符,并组装成类似于 Content-Type: multipart/form-data; boundary=... 的完整请求头。如果用户手动传入了不含 boundary 的 Content-Type,就会直接覆盖这一机制,导致服务端收到了多段数据却完全不知道从哪里开始切分。

其他常见问题与排查清单

  1. 文件未 Seek 到开头:如果一个文件对象已经被其它逻辑读取过(例如之前计算过 MD5 哈希),文件指针位于末尾,requests 将发送 0 字节的文件。在传递给 files 之前,应显式调用 file_obj.seek(0)。
  2. 字典值类型限制:在 data 参数中,所有字段的值建议为字符串、整数或布尔值。如果传递嵌套字典,requests 不会将其转为 JSON 字符串,建议显式使用 json.dumps() 转换为 JSON 格式字符串后再作为普通字段提交。
  3. 超时设置:文件上传涉及网络带宽与服务端写入延迟,务必设置合理的 timeout(如 timeout=(5, 60) 表示 5 秒连接超时,60 秒读取超时),避免程序永远挂起。

五、综合场景总结与方案速查

在实际开发中,根据上传数据源(磁盘文件还是内存流)、数据量大小以及是否需要监控进度,可以选择不同的实现模式。以下提供结构化决策参考:

Python requests发送multipart/form-data:文件与字段混合提交教程
图 4:不同混合上传模式与应用边界总结

总结与实战建议

使用 Python requests 提交包含文件与表单字段的 multipart/form-data 时,只要牢记以下三条核心准则,就能避免绝大多数通信故障:

  • 普通字段入 data,文件入 files:结构清晰、分工明确,充分利用 requests 原生的封装机制。
  • 文件必用二进制模式 'rb' 并管理生命周期:确保字节完整性,借助 with 语句防止资源泄露。
  • 切勿手动指定 Content-Type:完全交由底层根据字段内容动态生成附带边界符(Boundary)的标准头部。
相关专题:

本站声明

本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。

Python 相关产品和应用

全部下载

专题列表