本文详解如何用 Python requests 库以 multipart/form-data 格式上传文件（如图片、文档），对比 JSON 文本提交，涵盖底层原理、标准代码示例、文件句柄管理及常见注意事项。
本文详解如何用 python `requests` 库以 `multipart/form-data` 格式上传文件（如图片、文档），对比 json 文本提交，涵盖底层原理、标准代码示例、文件句柄管理及常见注意事项。
在 Web 开发中，向 REST API 提交数据有两种主流方式：发送结构化文本（如 JSON）和上传二进制文件。你当前使用的 json=data 参数会将字典序列化为 JSON 字符串，并以 Content-Type: application/json 发送——这适用于纯文本数据交互，但无法传输文件，因为 JSON 本身不支持二进制内容。
而文件上传必须使用 multipart/form-data 编码格式（即 cURL 中 -F 参数对应的机制）。该格式将请求体分割为多个“部分”（parts），每个部分可独立设置名称、文件名、MIME 类型和原始字节流，从而安全承载图像、PDF、CSV 等任意类型文件。
在 requests 库中，实现这一功能的关键参数是 files，而非 json 或 data。基本用法如下：
import requests
url = "https://abc.example.com/v1/upload"
files = {"image": open("/path/to/your/image.jpg", "rb")}
response = requests.post(url, files=files)
print(response.status_code)
print(response.text)⚠️ 注意：上述写法虽简洁，但存在资源泄漏风险——open() 返回的文件对象未显式关闭。强烈推荐使用上下文管理器（with 语句）确保文件句柄及时释放：
立即学习“Python免费学习笔记（深入）”；
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
import requests
url = "https://abc.example.com/v1/upload"
with open("/path/to/your/image.jpg", "rb") as f:
files = {"image": f} # 文件对象直接传入
response = requests.post(url, files=files)
print(f"Status: {response.status_code}, Response: {response.text}")更灵活的用法支持自定义文件名与 MIME 类型（当服务端依赖准确的 Content-Type 时尤为关键）：
files = {
"document": ("report.pdf", open("/tmp/report.pdf", "rb"), "application/pdf")
}
# 或使用 with 确保安全：
with open("/tmp/report.pdf", "rb") as f:
files = {"document": ("report.pdf", f, "application/pdf")}
requests.post(url, files=files)此外，若需同时提交表单字段（如 user_id、caption）与文件，可将普通字段放入 data 参数，files 仅负责文件部分：
data = {"user_id": "123", "caption": "My photo"}
with open("photo.jpg", "rb") as f:
files = {"image": f}
response = requests.post(url, data=data, files=files)总结：
- ✅ 用
files={key: file_obj}实现multipart/form-data上传； - ✅ 始终用
with open(...)管理文件生命周期； - ✅ 需要精确控制文件元信息时，使用三元组
("filename", fileobj, "content_type")； - ❌ 避免混用
json=和files=（requests 会忽略json，且可能引发编码冲突）； - ? 可通过
response.request.headers和response.request.body调试实际发出的请求头与原始 multipart 内容。
掌握这一机制，是你构建健壮文件上传功能的基础，也是理解前后端二进制协作的关键一步。
