asyncio.TimeoutError 是 asyncio 主动抛出的控制流信号，用于中断协程，并非必然表示请求失败或卡死；它不自动终止被等待协程，需显式清理资源，推荐用 async with asyncio.timeout() 实现自动取消与释放。
asyncio.TimeoutError 是什么，它真的代表超时了吗？
asyncio.TimeoutError 确实由超时触发，但它的出现不等于“网络请求失败”或“函数卡死”。它本质是 asyncio.wait_for() 或 asyncio.timeout() 主动抛出的控制流信号，用于中断正在运行的协程。常见于 await asyncio.wait_for(some_coro(), timeout=5) 场景中 —— 如果 some_coro() 未在 5 秒内完成，asyncio.TimeoutError 就会被 raise，而原协程可能仍在后台运行（除非你显式取消）。
容易踩的坑：
- 误以为抛出
asyncio.TimeoutError后，被等待的协程已自动终止 —— 实际上它可能还在执行、占用资源甚至修改状态 - 在
try/except中只捕获异常却忽略清理，导致连接泄漏（比如未关闭aiohttp.ClientSession）或任务堆积 - 把
asyncio.TimeoutError和TimeoutError（内置同步异常）混用，后者无法捕获异步超时
如何正确捕获并安全清理？
关键不是“抓到就完事”，而是“抓到后确保资源释放 + 协程可控终止”。推荐用 asyncio.timeout()（Python 3.11+）配合 async with，它会在退出时自动取消挂起的协程：
import asyncio
<p>async def fetch_data():
await asyncio.sleep(10) # 模拟慢请求
return "done"</p><p>async def main():
try:
async with asyncio.timeout(3):
result = await fetch_data()
print(result)
except asyncio.TimeoutError:
print("fetch_data 超时，已自动取消")
如果你用的是 Python
立即学习“Python免费学习笔记（深入）”；
- 用
asyncio.create_task()启动协程，保存 task 对象 - 在
except asyncio.TimeoutError:块中调用task.cancel() - 随后用
await asyncio.gather(task, return_exceptions=True)等待其真正结束（否则 cancel 只是“发信号”，协程可能还在跑）
timeout 参数设多少才合理？
不能拍脑袋填数字。真实服务中，超时值应分层设置：
- DNS 解析：通常
1–2秒（aiohttp默认aiodnsresolver 的timeout） - TCP 连接：建议
3–5秒（受网络抖动影响大，太短易误判） - HTTP 请求整体：需大于「连接超时 + 读取超时」之和，例如
connect=3,read=10→ 总体wait_for设为15秒更稳妥 - 避免全局统一设
timeout=1：对数据库查询或内部 RPC 来说，1 秒太激进；对健康检查来说，又太宽松
特别注意：aiohttp.ClientTimeout 的 total 字段和外层 asyncio.wait_for() 是叠加关系，重复设会导致意外提前中断。
为什么有时捕获不到 asyncio.TimeoutError？
最常见原因是协程里用了阻塞调用（如 time.sleep()、requests.get()），这会直接卡住整个 event loop，asyncio 的超时机制完全失效 —— 因为它依赖协程主动让出控制权。此时你看到的可能是程序“假死”，而不是抛出 asyncio.TimeoutError。
解决办法只有两个：
- 彻底替换阻塞调用：用
aiohttp替requests，用asyncio.sleep()替time.sleep() - 实在无法替换（如遗留 C 扩展），必须用
loop.run_in_executor()包装，否则 timeout 逻辑形同虚设
另一个隐蔽原因是异常被中间层吞掉：比如你在自定义 middleware 或装饰器里写了空 except Exception:，asyncio.TimeoutError 就悄无声息消失了。
