asyncio.wait_for() 必须配合可取消协程才真正生效，否则仅超时抛异常而目标协程仍在运行；需避免阻塞调用、正确处理取消信号、统一使用浮点型timeout并确保事件循环不被卡住。
asyncio.wait_for() 怎么用才真正生效
它不是给协程“加个超时装饰器”就完事的——必须确保被包裹的协程本身是可中断的，否则 asyncio.wait_for() 会干等到底，直到超时才抛 TimeoutError，但协程还在后台跑着。
常见错误现象：asyncio.wait_for(some_slow_coro(), timeout=1) 执行后，1 秒确实抛了 TimeoutError，但 some_slow_coro() 里的网络请求或计算仍在继续，甚至可能污染后续逻辑。
- 只对支持取消的协程有效：比如用
await asyncio.sleep()、await aiohttp.ClientSession.get()等原生异步操作；纯 CPU 密集型（如time.sleep(5)或大循环）会阻塞事件循环，wait_for拿不到控制权 - 超时后，目标协程会被调用
.cancel()，但是否响应取消取决于它内部有没有检查asyncio.current_task().cancelled()或是否用了可取消的 awaitable - 别嵌套多次
wait_for：外层超时可能比内层先触发，导致 cancel 链混乱，难以调试
timeout 参数传什么值才算安全
timeout 是 float 类型，单位秒，但精度受事件循环调度影响，实际误差通常在毫秒级。重点不在“多准”，而在“别传错类型”。
- 传
None表示不设限（等同于没用wait_for） - 传负数（如
-1）会立刻触发TimeoutError，可用于快速失败路径 - 传整数（如
5）完全合法，但建议统一用浮点（5.0），避免和某些接受 int 的同步函数混淆 - 不要动态拼接字符串再转 float，比如
float(os.getenv("TIMEOUT", "3"))—— 环境变量为空或非数字时直接炸
捕获 TimeoutError 后协程状态怎么清理
超时抛异常不等于协程已结束。如果它被 cancel 了但没处理取消信号，可能残留 task 在后台运行，甚至持有连接、文件句柄等资源。
立即学习“Python免费学习笔记（深入）”；
- 务必在
except asyncio.TimeoutError:块里显式await asyncio.shield()或asyncio.create_task()收尾？不，恰恰相反：应避免再 await 它，而是记录日志 + 主动 close 可控资源（如提前拿到的aiohttp.ClientSession） - 如果协程里开了子 task（比如
asyncio.create_task(sub_work())），主协程被 cancel 时子 task 不会自动 cancel，得自己管理生命周期 - 推荐模式：把待超时的逻辑封装进独立函数，并在入口处加
try/except CancelledError做清理，而不是依赖wait_for单方面兜底
为什么有时候 timeout 像没起作用
最常踩的坑不是代码写错，而是事件循环本身被卡住——wait_for 再准时，也得靠事件循环来调度 timer 和 cancel。
- 主线程执行了阻塞调用（如
requests.get()、time.sleep()、数据库 sync driver）：整个 loop 停摆，wait_for的定时器无法触发 - 协程里用了
asyncio.to_thread()但没设 timeout：子线程任务不受wait_for管控，只能靠to_thread自身的timeout参数 - 在 Jupyter 或某些测试框架里运行：它们可能替换了默认 loop，或未正确传播 cancellation，建议用
asyncio.run()起新 loop 测试最小复现 - Python 版本差异：3.11+ 对 cancellation 传播更严格，3.9 之前某些 awaitable（如旧版
aiofiles）可能忽略 cancel
超时机制本身很轻量，但它的可靠性完全系于整个异步执行环境是否“干净”。一旦混入同步阻塞或取消不响应的组件，asyncio.wait_for() 就只是个倒计时显示器，不是熔断开关。
