应使用 httpx.Timeout 显式设置 connect、read、write、pool 四维超时，而非传浮点数给 timeout 参数，否则无法精准控制各阶段行为，易在流式请求或高延迟场景下误判超时。
直接说结论：用 httpx.Timeout 显式构造多维超时对象，而不是传一个浮点数给 timeout 参数——否则你根本控制不了连接、读取、写入各阶段的行为，尤其在流式请求或高延迟场景下极易误判“超时”。
为什么传 timeout=5.0 会出问题
这是最常踩的坑。当你写 async with httpx.AsyncClient(timeout=5.0)，HTTPX 会把 5 秒同时塞进 connect / read / write / pool 四个维度。后果是：
- 连接慢但后续快？
connect=5.0可能刚够，但read=5.0对长轮询或 SSE 就太短，第一个 chunk 没来就断连 - 大文件上传？
write=5.0可能连 header 都没发完就被砍掉 - 连接池争抢激烈？
pool=5.0会让并发请求排队太久，实际延迟远超预期 - 错误类型难区分：所有超时都抛
httpx.TimeoutException，你无法判断是卡在 DNS、握手、还是服务器压根没响应
httpx.Timeout 各参数的实际作用场景
必须按阶段拆开设，才叫“精确控制”：
-
connect：DNS 解析 + TCP 三次握手 + TLS 握手总耗时。内网调用可设2.0，公网 API 建议5.0起步 -
read：从 socket 读到**任意一个字节**的最大等待时间（不是整个响应）。SSE 或流式下载必须单独拉高，比如30.0 -
write：把 request body 全部写进 socket 的时限。POST 大 JSON 或上传文件时重点调这个 -
pool：从连接池拿空闲连接的等待时间。并发量大时设低点（如1.0），避免请求堆积
示例：timeout = httpx.Timeout(connect=5.0, read=30.0, write=10.0, pool=1.0)
立即学习“Python免费学习笔记（深入）”；
Claw Code Suite (Python-Only Edition)
下载
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
流式请求（stream=True）的超时陷阱
很多人以为 stream() 的超时是“整个流持续时间”，其实不是。HTTPX 的 read 超时是“每块数据之间的间隔”：
- 服务器每 2 秒推一个 event —— OK，只要间隔 ≤
read值 - 第 3 次推送拖到 35 秒后 —— 触发
httpx.TimeoutException，连接被关，服务端报 “broken pipe” - 想让整个流持续 5 分钟？不能靠拉高
read，得配合心跳或重连逻辑，read本身只保单次接收不卡死
正确做法：设合理 read（如 45.0），并在循环读 chunk 时捕获异常，主动重试或降级。
和 asyncio.wait_for() 混用时的冲突点
别在外层再套 asyncio.wait_for(client.get(...), timeout=10) —— 这会造成双重超时，且语义混乱：
- HTTPX 内部已用
asyncio.timeout()（3.11+）或wait_for实现各阶段中断，外层再包一层，cancel 信号可能没传到底层 socket - 如果 HTTPX 的
connect超时是 5 秒，而你外层设了 10 秒，实际行为是：5 秒后 HTTPX 抛错，但外层wait_for还要等满 10 秒才结束 - 真正需要外层兜底的场景极少，仅限“整个请求流程含业务逻辑处理”（比如 fetch + parse + save），此时应把超时设在业务协程上，而非 HTTPX 客户端初始化时
一句话：HTTPX 自身的 timeout 已足够精细，除非有跨网络+跨计算的复合耗时需求，否则别叠甲。
最容易被忽略的是 pool 超时——它不报错，但会让你的并发请求在连接池里无声排队，监控上看就是“请求延迟突增但无超时异常”，查起来极费劲。
