httpx 默认不支持 HTTP/2,必须显式启用:安装 pip install "httpx[http2]",初始化 Client 或 AsyncClient 时传入 http2=True,且仅对 HTTPS 有效;需通过日志确认是否建立 HTTP/2 连接,并注意 header 限制。

httpx 默认不支持 HTTP/2,必须显式启用
Python 3.12 中的 httpx 默认走 HTTP/1.1,即使服务端支持 HTTP/2,httpx.Client() 也不会自动升级。要启用 HTTP/2,必须传入 http2=True 参数,并确保底层依赖满足要求。
常见错误现象:httpx.HTTPStatusError 或连接被重置,但实际是协商失败后退回到 HTTP/1.1,而某些 API(如 Cloudflare 代理后的 gRPC-Web 端点)会直接拒绝非 HTTP/2 请求。
- 必须安装带 HTTP/2 支持的后端:目前仅
httpcore[http2]可用,即运行pip install "httpx[http2]"(注意引号,避免 shell 解析错误) -
http2=True必须在Client初始化时指定,不能在.get()等方法中动态开启 - HTTP/2 要求 TLS(即
https://),对http://地址强制忽略http2=True,且不报错——这点极易被忽略
验证是否真的发出了 HTTP/2 请求
光看响应状态码或内容无法确认协议版本,因为 HTTP/2 响应头与 HTTP/1.1 表面一致。真正判断依据是连接层面的协商结果。
最可靠方式是启用 httpx 的日志并检查 httpcore 输出:
import httpx
import logging
logging.basicConfig(level=logging.DEBUG)
client = httpx.Client(http2=True)
client.get("https://www.php.cn/link/e0abf46439bd264af259e5cf868a0e6c")
若看到类似 httpcore.http2 - HTTP/2 connection established 的日志,说明成功;若只有 httpcore.http11 相关输出,则仍为 HTTP/1.1。
- 不要依赖
response.http_version字段——httpx当前(v0.27)未暴露该信息 - 某些 CDN(如 Fastly)会在响应头加
alt-svc,但这只表示“支持”,不代表本次请求用了 HTTP/2 - 本地测试可用
https://www.php.cn/link/e0abf46439bd264af259e5cf868a0e6c或https://http2.akamai.com/,它们明确返回 HTTP/2 流量
异步客户端也要显式开启 http2=True
很多人以为 AsyncClient 默认更“先进”,其实它和同步 Client 一样,默认关闭 HTTP/2。异步场景下漏掉 http2=True 是高频失误。
Python 环境工具专业版功能概述Python 环境工具专业版是一项面向实际任务的技能。它将相关步骤、工具调用和结果整理方式集中到统一流程中,帮助使用者更快完成目标并减少重复操作。核心要点使用时应结合输入条件选择合适的执行方式,核对必要参数、依赖环境与输出内容,并按原始要求处理异常情况。该技能适合需要稳定复用相关能力的场景,可作为自动化工作流的一部分,也便于后续检查、调整和扩展。执行完成后建议检查结果是否符合预期,并保留必要记录。使用与执行同时注意输入完整性、执行条件和输出可用性。从功能定位来看,该技能
示例:
import httpx
import asyncio
<p>async def fetch():
async with httpx.AsyncClient(http2=True) as client: # ← 这里必须写
r = await client.get("<a href="https://www.php.cn/link/e0abf46439bd264af259e5cf868a0e6c">https://www.php.cn/link/e0abf46439bd264af259e5cf868a0e6c</a>")
print(r.status_code)</p><p>asyncio.run(fetch())</p>
- 不能只在
get()里加参数,比如client.get(url, http2=True)是无效语法,会报TypeError - 使用
limits配置连接池时,HTTP/2 对连接复用更敏感,建议保持默认或显式设max_connections=100,避免过早断连 - 若遇到
httpcore.ConnectError: [Errno 104] Connection reset by peer,大概率是服务端不支持 HTTP/2 或 ALPN 协商失败,可先用curl -I --http2 https://example.com排查服务端能力
HTTP/2 下的 header 处理有隐含限制
HTTP/2 不允许自定义 Connection、Keep-Alive、Proxy-Connection 等逐跳头(hop-by-hop headers),httpx 会静默丢弃它们——这不同于 HTTP/1.1 的行为。
例如这段代码在 HTTP/1.1 下能发出去,在 HTTP/2 下完全无效:
client.get("https://api.example.com", headers={"Connection": "keep-alive"})
- 所有以冒号开头的伪头(如
:method)由httpx自动管理,手动设置会引发httpx.InvalidURL - HTTP/2 强制小写 header 名,
httpx会自动转换,但如果你依赖大小写敏感的中间件(比如某些旧版网关),可能出问题 - 二进制 header 值(如带非 ASCII 字符的
Authorization)需先 UTF-8 编码再 base64,否则触发UnicodeEncodeError—— 这在 HTTP/1.1 中有时被容忍,HTTP/2 更严格
HTTP/2 的核心不是“更快”,而是多路复用和头部压缩;但它的握手链路更长、依赖 TLS 配置和 ALPN,实际落地时最容易卡在依赖安装、协议协商日志缺失、以及 header 语义差异上。别只盯着 http2=True 这一行,得把整个链路(pip 安装 → client 初始化 → 日志验证 → header 检查)串起来看。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!










