如何在Python异步编程中处理asyncio.TimeoutError超时？-Python教程-PHP中文网

asyncio.timeouterror是asyncio.wait_for()或asyncio.timeout()主动抛出的控制流异常，用于中断等待过程而非表示任务执行失败；它继承自cancellederror，需配合正确异常处理与资源清理。

如何在python异步编程中处理asyncio.timeouterror超时？

asyncio.TimeoutError 是什么，它真的代表超时了吗？

不是所有 asyncio.TimeoutError 都是“你写的代码慢了”。它本质是 asyncio.wait_for() 或 asyncio.timeout() 主动抛出的控制流异常，用来中断等待任务——哪怕目标协程本身还没运行完。常见于 await asyncio.wait_for(fetch_data(), timeout=5) 这类写法。

容易踩的坑：把它当成网络层或系统级超时错误来捕获并重试，结果发现重试逻辑根本没执行（因为异常发生在等待阶段，而非目标协程内部）；或者在 try/except 里只捕获 TimeoutError 却漏了 asyncio.CancelledError，导致协程取消状态未被正确处理。

必须区分：超时是「等待过程」被中断，不是「任务执行」失败
asyncio.TimeoutError 继承自 asyncio.CancelledError，所以用 except asyncio.CancelledError: 也能捕获它（但不推荐，语义不清）
若目标协程内部有清理逻辑（如关闭连接），需确保它能响应取消——即要使用 async with 或 try/finally，而不是依赖超时后自动释放

怎么安全地捕获和响应 TimeoutError？

直接 except asyncio.TimeoutError: 没问题，但关键在于后续动作是否合理。比如 HTTP 请求超时后立即重试，可能加重下游压力；而数据库查询超时后直接返回缓存，可能更合适。

实操建议：

Python Testing

Python 测试速查：运行 pytest、使用 mock/patch、参数化、fixtures、异步、覆盖率测试。

下载

捕获位置要靠近 wait_for 或 timeout 调用点，避免异常向上冒泡到无关层级
不要在 except 块里再 await 同样的协程——它大概率已被取消，再次 await 会立刻抛 CancelledError
如果需要 fallback 行为，优先用同步值或本地缓存，而不是发起另一个异步调用

示例：

try:
    result = await asyncio.wait_for(api_call(), timeout=3)
except asyncio.TimeoutError:
    logger.warning("API call timed out, using default")
    result = DEFAULT_VALUE

asyncio.timeout() 和 asyncio.wait_for() 该怎么选？

asyncio.timeout()（Python 3.11+）是上下文管理器，asyncio.wait_for() 是函数式 API。两者语义不同，不能混用。

使用场景差异：

用 asyncio.timeout(5)：当你想给一整段异步逻辑加统一超时边界，比如整个请求处理流程（含解析、校验、写库）
用 asyncio.wait_for(task, timeout=5)：只对单个协程设限，适合调用外部服务这类明确可隔离的环节
wait_for 会隐式创建 task 并 cancel 它；timeout 不创建 task，只在 __aenter__ 时启动计时，在 __aexit__ 时检查是否超时
性能上无显著差别，但 timeout 更易嵌套（比如外层 10s，内层 2s），而 wait_for 嵌套容易出错

为什么有时 TimeoutError 捕获不到？

最常见原因是协程没被真正 await，或者超时机制没生效。比如：

忘了加 await，把协程对象直接传给 wait_for，结果等的是一个未运行的协程，wait_for 立刻超时
用了 asyncio.create_task() 但没 await 它，导致 wait_for 等的是 task 对象而非其结果
在 asyncio.to_thread() 里做 CPU 密集操作，超时检测无法中断线程，只能等线程自己结束——这时 TimeoutError 不会抛出
协程内部用了阻塞调用（如 time.sleep()），event loop 被卡住，超时机制失效