asyncio.to_thread专为不能改写但需在协程中调用的同步io函数设计，如requests.get、sqlite3.connect、json.load、cv2.imread；不适用于cpu密集型任务或原生异步io。
asyncio.to_thread 适合哪些阻塞函数？
它专为「不能改写但必须在协程里调用」的同步 IO 函数设计，比如 requests.get、sqlite3.connect、json.load（读文件）、cv2.imread 等。不是所有阻塞操作都适用：CPU 密集型任务（如 math.factorial(10**6)）更适合 loop.run_in_executor 配合 concurrent.futures.ProcessPoolExecutor；而纯异步 IO（如 aiohttp.ClientSession.get）根本不需要 to_thread。
怎么传参和捕获异常？
asyncio.to_thread 接收函数对象和位置/关键字参数，原样透传，但异常不会被吞掉——它会以原类型抛出，你得自己 try/except：
import asyncio
import requests
async def fetch_data():
try:
resp = await asyncio.to_thread(requests.get, "https://httpbin.org/delay/1")
return resp.json()
except requests.exceptions.ConnectionError as e:
print(f"网络不通: {e}")
return None
except Exception as e:
print(f"其他错误: {type(e).__name__}: {e}")
raise
- 参数直接跟在函数名后面，不用包成元组或字典
- 关键字参数也支持：
await asyncio.to_thread(open, "data.txt", "r", encoding="utf-8") - 若目标函数本身抛出异常，
to_thread不做转换，原封不动冒泡
线程池默认行为和潜在瓶颈
它背后用的是 asyncio.loop._default_executor，本质是 concurrent.futures.ThreadPoolExecutor，最大线程数默认为 min(32, os.cpu_count() + 4)。这意味着：
- 并发量大时（比如同时发起 100 个
to_thread调用），后到的任务会排队等空闲线程，不是立刻执行 - 无法控制线程名或设置超时（线程内超时需目标函数自身支持，如
requests.get(timeout=5)） - 若要自定义线程池（比如限制为 5 个线程），得手动创建
ThreadPoolExecutor并传给loop.set_default_executor，但注意这会影响整个 event loop 的所有to_thread和run_in_executor调用
常见报错：RuntimeError: no running event loop
这个错误只在没启动 event loop 时调用 await asyncio.to_thread(...) 才出现，典型场景是：
- 在普通函数里直接
await，没用asyncio.run()或loop.run_until_complete() - 在 Jupyter 中忘记用
await（IPython 7.0+ 支持 top-level await，但旧版或某些环境仍需显式运行） - 误把
to_thread当同步函数用了，比如写成asyncio.to_thread(...)而不是await asyncio.to_thread(...)
最稳妥的做法是确保调用栈顶层是 async 函数，并由 asyncio.run(main()) 启动。
线程切换开销小，但别把它当成“万能同步转异步开关”——IO 密集且无法异步改写的函数才值得这么用；否则，优先找原生异步库（aiofiles、aiosqlite、httpx.AsyncClient）更干净。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
