为 HTTPX 分别设置连接、读写与连接池超时

HTTPX 的五秒默认值限制网络不活动时间，不是一次请求的总时长。理解四类等待，才能把超时设置在正确的位置。

默认五秒究竟约束什么

HTTPX 默认在各处启用超时。官方文档把默认行为描述为：网络连续五秒没有活动时，抛出 TimeoutException。这不是“从发出请求起五秒内必须下载完所有内容”。如果响应持续有数据块到达，完整传输可能明显超过五秒。

这一区别在文件下载、流式 API 和长响应中尤其重要。调整超时前，先判断程序是在建立连接、等数据、发数据，还是等连接池里的空位。

给单次请求设置超时

顶层 API 和客户端实例都接受请求级 timeout 参数。下面将该请求使用的超时值设为十秒。与原文相比，这里把演示地址改为 HTTPS；地址仅用于说明接口，不是业务 API。

import httpx

response = httpx.get(
    "https://example.com/api/v1/example",
    timeout=10.0,
)

with httpx.Client() as client:
    response = client.get(
        "https://example.com/api/v1/example",
        timeout=10.0,
    )

需要明确禁用时，可以给单次请求传入 timeout=None，例如 client.get(url, timeout=None)。这表示该请求不再受 HTTPX 这些超时限制。它不是“沿用默认值”，也不是自动适应慢请求；服务或网络迟迟不完成时，调用可能一直等待。

为复用客户端设置默认值

如果同一客户端发出的请求具有类似的网络条件，可在创建时设置默认值：

import httpx

# 默认在各阶段采用 5 秒。
with httpx.Client() as client:
    pass

# 将该客户端的默认超时改为 10 秒。
with httpx.Client(timeout=10.0) as client:
    pass

官方同时展示了 httpx.Client(timeout=None)：它会在客户端层面禁用默认超时，影响此客户端后续未单独覆盖设置的请求。应当把这种行为视为明确选择，而不是推荐默认配置。

四类超时分别对应哪段等待

读超时和写超时的单位是一次块级等待，不是整个正文的累积传输时长。连接池超时则可能在真正连接远端之前发生：请求太多，而连接池没有可用连接，调用会先在池中等待。

官方文档特别指出，连接池等待与 limits 参数控制的最大连接数相关。因此，遇到 PoolTimeout 时，只把 read 从十秒加到六十秒，并不能直接解决连接池资源耗尽。还应核对并发数、连接上限，以及流式响应有没有按预期消费或关闭。

连接六十秒，其余十秒

httpx.Timeout 可以给公共默认值，再覆盖个别阶段。以下保留原文的六十秒连接预算和十秒其他预算，使用上下文管理器关闭客户端：

import httpx

timeout = httpx.Timeout(10.0, connect=60.0)
with httpx.Client(timeout=timeout) as client:
    response = client.get("https://example.com/")

这表示连接建立最多等待六十秒，读、写以及连接池等待使用十秒。若需要全部显式列出，同一组设置可以写成：

timeout = httpx.Timeout(
    connect=60.0,
    read=10.0,
    write=10.0,
    pool=10.0,
)

后一种写法是编辑补充的等价表达，不是新增的性能结论。超时设置也不会自动完成业务重试；重试是否安全，仍取决于请求是否幂等以及服务端是否已执行操作。

静态核对与使用边界

本稿只核对参数含义和代码结构，没有安装 HTTPX 或发送示例请求。上面的秒数沿用文档演示，并非针对某个生产服务测得的合适值。若业务要求“整项操作最多用时多少秒”，还需要在调用层建立独立的总截止时间或取消机制，不能把任一阶段的空闲超时当作总时限。

来源、署名与版本说明

原作者/维护方：未知（页面未单列作者）。本文为中文翻译与技术整理，编辑补充和修正已在文中标明。

• https://www.python-httpx.org/advanced/timeouts

原文为 HTTPX 官方文档，页面未单列文章作者。

核对日期：2026-10-05。源页为滚动文档，未在正文固定发行版本；使用 httpx.Timeout 与 Client 接口，部署时应核对安装版本。

Copyright © 2019, [Encode OSS Ltd](https://www.encode.io/).
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

* Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.