asyncio.to_thread 是 Python 3.9+ 提供的将同步函数提交至线程池执行的工具，适用于阻塞 I/O 操作或调用无法异步化的第三方库，但不适用于 CPU 密集型任务。
asyncio.to_thread 是什么，适合哪些场景
它不是把同步函数“自动变成”异步函数，而是把同步调用丢进线程池里执行，让当前 async 函数不被阻塞。适用于 CPU 不密集但会阻塞事件循环的 I/O 操作（比如 requests.get、json.load、某些数据库驱动的旧版接口），或者调用无法修改源码的第三方同步库。
注意：asyncio.to_thread 是 Python 3.9+ 才有的，3.8 及更早版本得用 loop.run_in_executor 模拟，而且要自己管理 ThreadPoolExecutor 实例。
怎么正确调用 asyncio.to_thread
直接传函数对象和参数，别加括号；返回的是一个 awaitable，必须用 await；不能传 lambda 或内联表达式（因为它们无法被 pickle，在多进程/跨线程时可能出问题，虽然 to_thread 当前只用线程，但习惯上避免）。
- ✅ 正确：
await asyncio.to_thread(requests.get, "https://httpbin.org/delay/1") - ❌ 错误：
await asyncio.to_thread(requests.get("https://..."))（这会立刻执行并传入返回值） - ❌ 错误：
await asyncio.to_thread(lambda: time.sleep(1))（推荐改用asyncio.sleep，或封装成具名函数）
常见错误：阻塞没消失，甚至更慢了
根本原因通常是线程没真正“并发”，或者任务本身不适合扔线程——比如你在线程里反复做小量计算，反而因上下文切换和 GIL 争抢变慢；或者忘了 await，导致 to_thread 返回的协程对象被当成普通对象忽略，后续逻辑直接报错或静默失败。
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
立即学习“Python免费学习笔记（深入）”；
- 检查是否漏了
await：返回值是coroutine对象，不是结果 - 避免在线程里做纯 CPU 工作（如
sum(range(10**7))）；该用ProcessPoolExecutor的地方别硬塞to_thread - 不要为单次小操作（比如读本地小文件）套一层
to_thread，开销可能比操作本身还大 - 如果原函数依赖线程局部状态（
threading.local），在线程池中行为不可预测，慎用
和 loop.run_in_executor 对比，什么时候选哪个
asyncio.to_thread 是对 loop.run_in_executor(None, ...) 的简化封装，底层共用同一个默认线程池（concurrent.futures.ThreadPoolExecutor，最大线程数通常为 min(32, (os.cpu_count() or 1) + 4)）。区别在于：
-
to_thread更简洁，适合简单调用； - 需要复用特定线程池（比如限制并发数、设置初始化函数）、或需要在 Python 3.8 运行时，就得用
run_in_executor显式传入executor； - 若需取消任务、获取 Future 状态、或组合多个 executor 行为，也得退回
run_in_executor； - 两者都不解决 GIL 限制——CPU 密集型任务仍会卡住其他线程，只是不卡 event loop 而已。
线程池大小、任务排队策略、异常传播方式这些细节，一旦脱离默认行为，就很容易掉进配置黑洞。真要用定制 executor，建议先测满载下的排队延迟和内存增长，而不是只看单次调用是否“成功”。
