直接传 timeout 参数常不生效,因 aiohttp 超时需用 ClientTimeout 实例,分 connect、sock_read、total 三层控制;连接复用需正确配置 TCPConnector 的 limit、keepalive_timeout 等参数。

为什么直接传 timeout 参数经常不生效?
aiohttp 的超时控制不是靠给 session.get() 传一个数字搞定的。它分三层:连接建立、读响应头、读完整响应体,缺一不可。只设 timeout=5 会触发 TypeError,因为 timeout 必须是 aiohttp.ClientTimeout 实例。
常见错误现象:TypeError: timeout must be None or aiohttp.ClientTimeout;或看似设了超时,但 DNS 卡住、SSL 握手失败时仍死等。
- 必须显式构造
aiohttp.ClientTimeout,例如aiohttp.ClientTimeout(total=10, connect=5) -
total是总上限,包含连接、重定向、读取全部阶段;connect仅限 TCP 连接+TLS 握手;sock_read控制每次 socket 读的等待(防大文件卡住) - 若未指定
connect,默认为total值,但 DNS 解析失败时可能无法及时中断
如何让连接真正复用而不每次都新建 TCP?
aiohttp 默认开启连接池,但复用的前提是:相同 host+port+ssl 设置下,且连接未被服务器主动关闭、未超空闲时间。很多人误以为开了 session 就自动长连接,结果抓几百个请求发现 TIME_WAIT 爆增——其实是没配对连接池参数。
使用场景:高频调用同一 API(如内部微服务),或批量爬取固定域名下的资源。
立即学习“Python免费学习笔记(深入)”;
当现有的脚本或服务需要将作用域化的仓库工作委托给 Claude Code 并以编程方式消费结构化响应时,请使用 Claude Agent SDK for Python。
- 创建
aiohttp.TCPConnector时设limit=100(单 host 并发上限)和limit_per_host=30(防被限流) - 务必设
keepalive_timeout=30(默认 15s),匹配服务端的keep-alive: timeout=30头,否则连接很快被关 - 加
force_close=False(默认值,但显式写更安心),避免每次请求后主动发 FIN - 注意:HTTPS 下 SNI 和证书验证也影响复用,若混用不同子域但共用 IP,需确认是否启用了
use_dns_cache=True(默认开启)
超时与复用组合配置的实际写法
把超时和连接池捏在一起才真正可控。单独设 timeout 或 connector 都可能漏掉关键环节。
import aiohttp
import asyncio
<p>timeout = aiohttp.ClientTimeout(
total=15,
connect=7, # DNS+TCP+TLS 必须在 7s 内完成
sock_read=8, # 每次读响应体最多等 8s,防大响应卡死
)</p><p>connector = aiohttp.TCPConnector(
limit=50,
limit_per_host=20,
keepalive_timeout=30,
force_close=False,
)</p><p>async def fetch(url):
async with aiohttp.ClientSession(
timeout=timeout,
connector=connector,
) as session:
async with session.get(url) as resp:
return await resp.text()</p><h1>调用</h1><p>asyncio.run(fetch("<a href="https://www.php.cn/link/ef246753a70fce661e16668898810624">https://www.php.cn/link/ef246753a70fce661e16668898810624</a>"))
注意:ClientTimeout 是 session 级别传入的,不是每个 get() 单独传;connector 同理,复用逻辑由 session 统一管理。
容易被忽略的坑:DNS 缓存、SSL 重协商与 HTTP/2
DNS 解析默认缓存 10 分钟,但若服务端轮转 IP,旧连接可能复用失败;HTTPS 下 TLS 重协商会额外耗时,而 connect 超时不包含这部分;HTTP/2 复用更强,但 aiohttp 1.x 默认不启用,需手动配 connector = aiohttp.TCPConnector(..., enable_http2=True)(要求 Python ≥ 3.9 + OpenSSL ≥ 1.1.1)。
- 开发期可临时禁用 DNS 缓存:
TCPConnector(use_dns_cache=False),上线前再开 - 遇到
ServerDisconnectedError频发,先检查服务端是否发送了connection: close或设置了极短的keep-alive: timeout=5 - HTTP/2 开启后,
limit_per_host对单个连接的多路复用更关键,建议调低到 10–15,避免单连接压垮服务端
真正难调的从来不是“怎么写”,而是“哪个环节在拖慢你”——超时值得怀疑,连接复用效果得看 session.connector._conns 的实际长度,而不是文档里写的“默认开启”。

















