Python asyncio.wait_for 超时后底层任务为什么还在运行

你看到“asyncio.wait_for 已经超时，但底层任务还在运行”，多数时候并不是超时失效，而是把三个状态混在了一起：超时触发、任务收到取消、任务完成清理。wait_for 超时后会取消被等待对象，并等待它真正结束取消流程，所以底层协程的 finally 较慢时，TimeoutError 也会晚一点返回；如果包了 asyncio.shield，底层任务则会被刻意保留下来。

wait_for 的超时其实分成两段

先用一个带清理延迟的协程观察现象。这里的 timeout=0.1 只表示等待预算，不代表底层任务会在 100 毫秒内瞬间消失。

import asyncio
import time

async def slow_job():
    try:
        await asyncio.sleep(1)
    finally:
        # 模拟关闭连接、回收临时文件等取消后的清理
        await asyncio.sleep(0.3)

async def main():
    task = asyncio.create_task(slow_job())
    started = time.perf_counter()
    try:
        await asyncio.wait_for(task, timeout=0.1)
    except TimeoutError:
        elapsed = time.perf_counter() - started
        print(f"超时异常已返回，耗时约 {elapsed:.1f} 秒")
        print(f"done={task.done()} cancelled={task.cancelled()}")

asyncio.run(main())

关键观察不是精确耗时，而是两个状态：异常返回时 task.done() 通常已经为真，task.cancelled() 也为真；但返回时间可能明显大于 0.1 秒，因为 wait_for 要等取消和 finally 收尾。任务如果捕获取消后还要做清理，调用方就不能把 timeout 当成硬性的总耗时上限。

直接取消和 shield 保护要分开判断

如果业务要求“请求超时就停止工作”，直接把协程交给 wait_for 即可。如果任务代表必须完成的落盘、消息确认或缓存刷新，才考虑 shield，并明确接受它会脱离当前调用的生命周期。

async def compare_modes():
    protected = asyncio.create_task(slow_job())
    try:
        # shield 只保护底层任务，外层 wait_for 仍会超时
        await asyncio.wait_for(asyncio.shield(protected), timeout=0.1)
    except TimeoutError:
        print(f"外层结束：done={protected.done()} cancelled={protected.cancelled()}")
        await protected  # 这里等待被保护任务完成，生产代码可改为回调或队列

asyncio.run(compare_modes())

此时超时异常发生时，protected.cancelled() 应为假，任务还可能在执行。不要写成 await asyncio.wait_for(asyncio.shield(coro()), ...) 后就丢掉任务；为 Task 保留强引用，才能在超时后查询状态、等待结果或记录失败。

在 finally 清理中不要吞掉 CancelledError

取消是协作式的：事件循环在任务下一次可挂起的位置抛出 CancelledError。资源释放放进 finally，必要时记录上下文，但不要用宽泛的 except Exception 误判取消，也不要清理后静默返回成功。

shield 和 TaskGroup 应该放在哪个边界

shield 适合保护一个有独立生命周期的 Task；TaskGroup 适合把多个相互依赖的任务放在同一个协作边界里。组内一个任务抛出非取消异常时，其他任务会被取消，退出上下文时还会等待它们结束。因此，不要为了“让某个子任务继续”随意在整个组外套一层 shield，那会让组的生命周期和资源所有权变得难以判断。

async def other_job():
    await asyncio.sleep(2)

async def run_group():
    try:
        async with asyncio.TaskGroup() as group:
            # 组内任务共享生命周期，失败时由 TaskGroup 收敛取消
            group.create_task(slow_job())
            group.create_task(asyncio.wait_for(other_job(), timeout=0.5))
    except* TimeoutError:
        # TaskGroup 会把子任务异常组合起来；取消不应被当成普通成功
        print("组内超时，相关任务已进入收尾")

asyncio.run(run_group())

如果整个协作单元都必须受一个总预算约束，可以在调用 run_group() 的外层使用 wait_for；如果只是单个子操作可以独立失败，则把超时放在该子操作附近。判断标准是资源是否共享、失败是否应该连带取消，而不是哪个写法更短。

常见问题

wait_for 的 timeout 是总耗时上限吗？

不是严格的总耗时上限。超时会触发取消，但 wait_for 还要等待被取消对象完成清理；清理逻辑不返回时，调用方也会继续等待。

超时后如何让任务继续运行？

先用 asyncio.create_task 保存任务，再把这个 Task 放进 asyncio.shield。同时安排明确的结果回收、异常记录和最终取消，避免留下无人管理的后台任务。

为什么捕获 CancelledError 后 TaskGroup 可能表现异常？

TaskGroup 和超时上下文内部都依赖取消来收敛任务。若业务确实捕获它，应完成清理后重新抛出；只有明确要消除取消状态时，才进一步处理取消计数。