本文内容
要将 curl 转换为 Python,请把命令中的 URL、请求方法、请求头和请求体对应到一次 Requests 调用,然后比对服务器实际收到的内容。可以先从下面的成对示例入手,并明确选择重定向行为。
仅凭响应成功并不能证明两者等价。我们在 localhost 上的测试发现,即使代码看起来正确,直接翻译也可能改变 JSON 字节、表单编码和重定向行为。
关键要点
- 我们的 localhost 快照涵盖六个测试用例,每个客户端各重复三次。
- 测试共包含 36 次初始客户端执行,不含重定向后续请求。
- 重复查询用例保留了参数顺序和重复的键。
- JSON 用例保留了数据,但改变了请求体字节。
- 表单用例把字面空格变成了加号。
- 重定向用例中,curl 只发出一次请求,而 Requests 发出了两次。
如何用 Requests 将 curl 转换为 Python?
一次只翻译一个请求,并让它的目标地址和输入始终清晰可见。下面这个 GET 示例会向公共回显端点发送重复的查询参数和一个自定义请求头;在那里请只使用合成数据。
python -m pip install requests
curl --silent --show-error 'https://httpbin.org/get?tag=a&tag=b&page=2' -H 'X-Test: 1'
import requests
response = requests.get(
'https://httpbin.org/get',
params=[('tag', 'a'), ('tag', 'b'), ('page', '2')],
headers={'X-Test': '1'},
allow_redirects=False,
timeout=(5, 20),
)
response.raise_for_status()
print(response.status_code)
print(response.json()['args'])
端点正常响应时,您应当看到状态码 200,以及与 {'page': '2', 'tag': ['a', 'b']} 等价的参数。字典的显示顺序在这里无关紧要,但重复的值不能丢。
Requests 快速入门介绍了查询参数、请求头和响应处理。对于您自己的端点,请先替换 URL,然后每次只改动一项输入,这样出现故障时更容易定位。
curl 到 Python 的哪些参数映射最重要?
要映射的是请求的含义,而不只是参数的写法。curl 手册和 Requests API 参考说明了这份转换清单背后的各个选项。
| curl 输入 | Requests 等价写法 | 检查要点 |
|---|---|---|
| -X POST | requests.post(…) 或 request(‘POST’, …) | 核对实际使用的方法,包括由请求体选项隐含的方法。 |
| URL 查询或 -G | params= | 需要时保留重复的键和顺序。 |
| -H | headers= | 保留必需的值。 |
| -b ‘name=value’ | cookies= | Cookie 文件需要单独处理。 |
| -u(Basic 身份验证) | auth=(username, password) | 不要假定所有身份验证方案都是 Basic。 |
| Authorization: Bearer 请求头 | headers={‘Authorization’: …} | 从密钥来源读取令牌。 |
| -d 或 –data-raw | data= 或 json= | 根据请求体格式和字节要求选择。 |
| -F | files=,可搭配 data= | 核对文件名和字段名。 |
| -L | allow_redirects=True | 明确设置重定向策略。 |
| -x | proxies= | 保留代理协议方案和路由。 |
参数翻译并非总是一一对应。对于特殊的签名、证书、DNS 和协议选项,请将其作为单独的检查项。在确认哪些源请求头重要时,可以参考我们的 curl 请求头指南。
如何保留 JSON、表单和文件上传的内容?
结构化 JSON 使用 json=,表单字段或精确的请求体字节使用 data=,multipart 上传使用 files=。这些接口记录在 Requests 请求体与上传示例中。
POST 请求也可以携带查询参数。下面的示例把查询参数与 JSON 请求体分开,并从环境变量中读取 Bearer 令牌。运行之前,请把 API_URL 设置为您已获授权的端点,并通过您常用的密钥机制设置 API_TOKEN。
import os
import requests
response = requests.post(
os.environ['API_URL'],
params=[('mode', 'validate')],
headers={'Authorization': 'Bearer ' + os.environ['API_TOKEN']},
json={'name': 'a', 'n': 1},
allow_redirects=False,
timeout=(5, 20),
)
response.raise_for_status()
print(response.status_code)
对于需要签名的请求体,请只序列化一次,并对实际发送的同一份字节进行签名。我们的 JSON 用例在翻译过程中改变了空白字符。紧凑序列化可以还原该用例的原始请求体,但无法还原任意的原始空白字符或键顺序。
import json
import os
import requests
body = json.dumps({'name': 'a', 'n': 1}, separators=(',', ':')).encode('utf-8')
response = requests.post(
os.environ['API_URL'],
data=body,
headers={'Content-Type': 'application/json'},
allow_redirects=False,
timeout=(5, 20),
)
response.raise_for_status()
对于重复的表单字段,请使用 data=[('k', '1'), ('k', '2'), ('x', 'a b')]。在我们的测试中,这会把空格编码为 +,而 curl 的字面 -d 输入则保留了空格。curl 的 –data-urlencode 选项会对字段值编码,但解码后等价并不意味着字节一致。
对于上传,请让客户端自行生成 multipart 边界。这个自包含的示例使用合成文件内容;请把文件内容和字段名与 multipart 外层封装分开比对。
import os
import requests
response = requests.post(
os.environ['API_URL'],
data={'label': 'example'},
files={'file': ('sample.txt', b'hello\n', 'text/plain')},
allow_redirects=False,
timeout=(5, 20),
)
response.raise_for_status()
如何安全地复制浏览器请求?
只捕获已获授权的请求,并在分享之前删除其中的密钥。在 Chrome 开发者工具中,打开 Network 面板,右键点击请求并选择 Copy > Copy as cURL,详见 Chrome Network 参考文档。
执行任何内容之前,请先检查这段文本。Shell 引号属于命令语法,不一定属于请求负载。请对照捕获时所用的 shell,检查其中嵌入的引号、续行符和变量引用。
请把授权信息和会话值转移到密钥存储中。保留必需的应用请求头,但在复制之前要检查捕获到的 Host、Content-Length 和浏览器专有请求头。请逐个删除可疑的请求头并重新测试;一次性全部删除会让您看不出究竟是哪个值起了作用。
请记录捕获时间和预期操作。复制的请求只是一份快照,会话过期或应用状态变化都可能使它失效。翻译并不等于模拟浏览器,也不能重现完整的交互过程。
什么时候该用转换器,什么时候该换一种方式?
对于需要长期维护的代码,请手动转换;转换器适合用来生成可供检查的初步翻译。如果保留 curl 的行为比使用原生 Python HTTP 客户端更重要,请继续使用 curl。
| 方式 | 适合使用的情况 | 应避免使用的情况 |
|---|---|---|
| 手动转换为 Requests | 当您需要易读且可维护的代码时,适合手动转换为 Requests。 | 当仍有特殊的 curl 行为未被映射时,应避免手动转换为 Requests。 |
| curlconverter | 当您想要一份起步翻译时,适合使用 curlconverter。 | 当您无法审查生成的代码或无法保护凭据时,应避免使用 curlconverter。 |
| 通过 subprocess 保留 curl | 当必须沿用现有的 curl 行为时,适合使用 subprocess。 | 当命令内容不可信,或必须使用原生 Python 时,应避免使用 subprocess。 |
curlconverter 官方网站称转换在您的浏览器中完成。这一说法只适用于该网站,并不适用于所有 curl 转 Python 的转换器。其官方仓库记录了下面这条 CLI 路径:
npm install --global curlconverter
curlconverter --language python 'https://httpbin.org/get'
从 Python 中执行 curl 是另一种做法。请遵循 Python subprocess 文档,使用固定的参数列表,并避免 shell 求值。同时仍要检查每一个参数和目标地址。
import subprocess
result = subprocess.run(
['curl', '--silent', '--show-error', '--fail',
'--max-time', '20', 'https://httpbin.org/get'],
check=True,
capture_output=True,
text=True,
timeout=25,
)
print(result.stdout)
如何检查转换是否等价?
使用四层请求等价性检查,把应用层输入一致、字节一致和响应行为一致区分开来。在接受转换结果之前,请先确定您的端点需要满足哪些属性。

- 第 1 层,目标地址和方法:比对方法、路径和有序的查询参数对。
- 第 2 层,请求头和身份验证:比对选定的请求头值和凭据位置,同时不要记录密钥。
- 第 3 层,请求负载:比对原始请求体长度、SHA-256 和解析后负载的一致性。
- 第 4 层,传输和响应:比对状态码、最终 URL 和重定向跳数。
在我们于 2026 年 10 月 15 日进行的测试中,一个绑定到 127.0.0.1 的日志 HTTP 服务器收到了六个测试用例,每个客户端各运行三次。也就是 36 次初始执行,重定向后续请求另算。三次运行的结果保持一致。
来源:DataImpulse,CURL vs PYTHON REQUESTS EQUIVALENCE TEST,2026 年 10 月 15 日 16:12 UTC。Linux 环境使用 curl 8.5.0、Python 3.12.3 和 Requests 2.34.2。这是一次 localhost 快照,不是基准测试。
| 测试用例 | 语义一致 | 字节一致 | 重定向一致 | 说明 |
|---|---|---|---|---|
| 重复查询 | 是 | 是(查询部分) | 未涉及 | 元组对保留了 tag=a、tag=b 和 page=2。 |
| 自定义请求头和 Cookie | 是 | 是(选定的值) | 未涉及 | X-Test 和合成 Cookie 一致。 |
| Bearer 请求头 | 是 | 是(选定的值) | 未涉及 | 合成的授权值一致。 |
| JSON POST | 是 | 否 | 未涉及 | 新增的空格改变了请求体哈希。 |
| 重复的表单字段 | 解码后的字段相同 | 否 | 未涉及 | 字面空格变成了 +。 |
| 302 重定向 | 仅限初始请求 | 整个重定向链未确认 | 否 | curl 发出一次请求,Requests 发出两次。 |
上表中的字节一致仅针对所列字段,而不是完整的传输报文。两个客户端的 User-Agent 不同。这份快照无法确定与外部 API 的兼容性、TLS 行为、代理性能或普遍适用的成功率。
要进行您自己的可重复检查,请保留已脱敏的命令、服务器代码和软件包版本,并分别记录这四层的日志。请用两个客户端都停止跟随重定向的方式重复重定向用例,再用两个客户端都跟随的方式重复一次;这些是后续验证步骤,并不是本文报告的额外实测结果。
为什么转换后的代码会失败或返回不同的结果?
在同时更改多项设置之前,请先找出第一个出现差异的层。请使用同样的已授权输入,让原始命令和转换后的请求在时间上尽量接近。
- 身份验证:检查凭据是否过期、作用范围以及所需的会话状态。排查 401 或 403 时,切勿打印令牌。
- 重定向:在比较最终内容之前,先检查初始响应。我们的用例立即暴露了默认行为的不同。
- 编码:当签名或精确的请求负载很重要时,请比对字节;当应用层含义很重要时,请比对解码后的字段。
- HTTP 错误:检查状态码和已脱敏的响应片段。Requests 提供 raise_for_status() 来处理不成功的 HTTP 状态。
- 超时:明确设置连接和读取的值。它们并不是总耗时的截止时间。
- TLS:应纠正证书信任或主机名问题。关闭验证会带来被拦截的风险。
- 流式传输:请有意识地读取响应并将其关闭;对流式下载使用上下文管理器。
Requests 快速入门涵盖了状态处理,而高级用法则讲解了超时、证书验证和流式传输。在添加重试之前,请先诊断故障原因,对于会改变服务器状态的操作尤其如此。
代理如何融入转换后的请求?
请在直连转换成功之后再翻译路由。代理身份验证要与目标服务的 Bearer 令牌或 Cookie 分开处理。
import os
import requests
proxy_url = os.environ['PROXY_URL']
response = requests.get(
os.environ['API_URL'],
proxies={'http': proxy_url, 'https': proxy_url},
allow_redirects=False,
timeout=(5, 20),
)
response.raise_for_status()
print(response.status_code)
Requests 在其代理文档中说明了代理 URL、内嵌的代理身份验证以及环境变量代理设置。当结果不一致时,请检查环境变量中的路由。SOCKS 需要可选依赖项;除了代理地址之外,还要保留预期的 DNS 行为。
请使用 curl 代理设置指南来检查源命令,并参考 Python Requests 代理教程来编写目标代码。等价性检查通过之后,可以选择阅读 Python 路由指南和 curl 路由指南作为后续步骤。
常见问题
如何将 curl 命令转换为 Python Requests?
把 curl 请求拆分为目标地址、方法、请求头和请求负载,然后逐一翻译。在采用结果之前,请比对服务器端的观察结果;仅仅执行成功是不够的。
curl 的 JSON、表单和上传选项如何对应到 Python?
JSON 对象选择 json=,表单字段或精确字节选择 data=,multipart 上传选择 files=。对于对字节敏感的请求,请保留原始请求体并验证其哈希,而不要假定序列化会保持不变。
如何安全地保留请求头、Cookie 和 Bearer 身份验证?
先列出所需的值,并在运行时加载真实密钥。分享示例时请使用合成的替代值,并避免记录目标服务凭据或代理凭据。
为什么转换后的 Python 代码与原始 curl 命令的行为可能不同?
我们的快照暴露了请求体序列化和重定向处理方面的差异。在把不同的输出归因于远程服务之前,请先检查初始请求和响应。
如何把 curl 的代理设置翻译为 Requests?
把代理端点放入 proxies 映射,并保留其协议方案。在比较结果之前,请将环境变量路由和代理身份验证与应用身份验证分开检查。
解析后的 JSON 一致能证明转换正确吗?
它只能证明被比较的负载解码后得到相同的数据。我们的 JSON 用例的请求体哈希仍然不同,当验证依赖精确字节时,这一点很重要。
转换成功后还需要代理路由吗?
如果您已获授权的工作流需要代理路由,请先阅读 DataImpulse Requests 设置指南。DataImpulse 不是网络爬取 API、托管式解封工具或 VPN;请求的正确性和响应处理仍然是您代码的一部分。
最后更新:2026 年 10 月 15 日。
