A curl command beside Python Requests code with checks for destination, headers, payload and response behavior

要将 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)

如何检查转换是否等价?

使用四层请求等价性检查,把应用层输入一致、字节一致和响应行为一致区分开来。在接受转换结果之前,请先确定您的端点需要满足哪些属性。

您的 Python 请求真的和 curl 命令一样吗?

  • 第 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 日。


Share article: