本文详解如何将 API 返回的 PDF 二进制数据准确写入本地文件，重点纠正使用 response.text 导致文件损坏的常见错误，并提供安全、可靠的保存方案。
本文详解如何将 api 返回的 pdf 二进制数据准确写入本地文件，重点纠正使用 `response.text` 导致文件损坏的常见错误，并提供安全、可靠的保存方案。
在调用返回 PDF 文件的 REST API（如生成报告、导出合同等场景）时，开发者常误将响应体当作文本处理，结果导致生成的 PDF 打不开、空白或报“损坏的文件”错误。根本原因在于：PDF 是二进制格式，其内容包含不可见控制字节、压缩流（如 /FlateDecode）及特殊编码（如 %PDF-1.4 头部），无法通过 UTF-8 或其他文本编码无损解析。
错误做法示例（务必避免）：
# ❌ 错误：使用 response.text —— 自动解码为字符串，破坏二进制结构
data = response.text
with open("output.pdf", "wb") as f:
f.write(data.encode("utf-8")) # 即使再 encode，原始字节已失真
# ❌ 错误：对 text 进行 base64 编码 —— 双重编码，逻辑混乱
import base64
encoded = base64.b64encode(response.text.encode("utf-8"))
with open("broken.pdf", "wb") as f:
f.write(encoded)✅ 正确做法：始终使用 response.content
requests 库的 response.content 属性直接返回原始 bytes 类型响应体，未经任何字符解码，完美保留 PDF 的二进制完整性：
import requests
# 示例：调用返回 PDF 的 API
response = requests.get("https://api.example.com/report?format=pdf")
response.raise_for_status() # 检查 HTTP 状态码（如 404/500）
# ✅ 关键：直接写入 response.content（bytes）
with open("report.pdf", "wb") as f:
f.write(response.content)? 补充最佳实践：
- 验证响应头：检查 Content-Type: application/pdf 和 Content-Length，辅助判断响应有效性；
-
处理大文件：避免内存溢出，可流式写入：
with open("large.pdf", "wb") as f: for chunk in response.iter_content(chunk_size=8192): f.write(chunk) -
添加文件扩展名与 MIME 检查（增强健壮性）：
if response.headers.get("content-type") != "application/pdf": raise ValueError("API did not return a PDF")
总结：PDF 是二进制资源，不是文本。永远优先使用 response.content 而非 response.text；跳过任何中间编码/解码步骤；配合异常处理与头信息校验，即可稳定、高效地完成 API PDF 下载任务。
