Python requests发送multipart/form-data:文件与字段混合提交教程
本文详细介绍如何使用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 参数传递文件对象。
二、基础实战:同时提交文本字段与单个文件
在进行混合提交时,最稳健的做法是将纯文本参数放入一个字典赋值给 data,并将以二进制模式打开的文件对象包装进字典赋值给 files。
完整基础代码示例
以下是在实际工程中最常用的标准写法。请务必使用 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}")
如果以默认的 '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 参数或后端获取到的所有字段与文件均为空)。
multipart/form-data 报文中,必须依靠一串不会在正文中重复出现的边界标识符(如 ----WebKitFormBoundary7MA4YWxkTrZu0gW)来区分“字段 A 结束”、“文件开始”、“文件结束”。
当 requests 检测到传入了 files 参数时,它会自动在底层计算随机边界符,并组装成类似于 Content-Type: multipart/form-data; boundary=... 的完整请求头。如果用户手动传入了不含 boundary 的 Content-Type,就会直接覆盖这一机制,导致服务端收到了多段数据却完全不知道从哪里开始切分。
其他常见问题与排查清单
-
文件未 Seek 到开头:如果一个文件对象已经被其它逻辑读取过(例如之前计算过 MD5 哈希),文件指针位于末尾,
requests将发送 0 字节的文件。在传递给files之前,应显式调用file_obj.seek(0)。 -
字典值类型限制:在
data参数中,所有字段的值建议为字符串、整数或布尔值。如果传递嵌套字典,requests不会将其转为 JSON 字符串,建议显式使用json.dumps()转换为 JSON 格式字符串后再作为普通字段提交。 -
超时设置:文件上传涉及网络带宽与服务端写入延迟,务必设置合理的
timeout(如timeout=(5, 60)表示 5 秒连接超时,60 秒读取超时),避免程序永远挂起。
五、综合场景总结与方案速查
在实际开发中,根据上传数据源(磁盘文件还是内存流)、数据量大小以及是否需要监控进度,可以选择不同的实现模式。以下提供结构化决策参考:
总结与实战建议
使用 Python requests 提交包含文件与表单字段的 multipart/form-data 时,只要牢记以下三条核心准则,就能避免绝大多数通信故障:
- 普通字段入
data,文件入files:结构清晰、分工明确,充分利用 requests 原生的封装机制。 - 文件必用二进制模式
'rb'并管理生命周期:确保字节完整性,借助with语句防止资源泄露。 - 切勿手动指定 Content-Type:完全交由底层根据字段内容动态生成附带边界符(Boundary)的标准头部。
本站声明
本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。













