ContextVar 到线程池就丢了？asyncio.to_thread 和 run_in_executor 实测

异步代码里经常会放一个 request_id、trace_id 或 tenant_id 到 ContextVar。这样业务函数不用层层传参，日志、追踪和审计代码就能在当前任务里读取它。

问题出现在把同步函数交给线程池之后：同一段读取代码，放进 asyncio.to_thread 能拿到请求上下文，换成 loop.run_in_executor 却可能只得到默认值。两种写法看起来都是"把函数扔到线程里执行"，实际并不等价。

我在 Windows 11、Python 3.13.13 上用同一组 ContextVar 做了对照实验。结果不只验证了两条 API 的差别，还发现两个容易被忽略的边界：to_thread 到底在什么时候复制上下文，以及复制上下文是否意味着里面的可变对象也被隔离。

一、先看症状：同一个变量，换一种线程池入口就变了

假设一个 Web 请求进入异步服务时，框架或中间件设置了请求标识：

from contextvars import ContextVar

request_id = ContextVar("request_id", default="MISSING")
request_id.set("req-20261107-01")

在当前异步任务里，request_id.get() 可以读到请求标识。接下来，业务代码需要调用一个同步库，于是把读取动作放进线程池。

如果使用 asyncio.to_thread，通常能读到原值；如果直接调用 loop.run_in_executor，工作线程里可能读到 MISSING。代码没有报错，线程也正常执行，只是日志上下文悄悄丢了。

这类问题很难靠异常监控发现。接口返回可能完全正常，数据库写入也可能成功，只有日志关联、链路追踪、租户审计或灰度标记出现断层。排查时如果只看主协程里的 ContextVar，很容易误以为请求上下文始终存在。

先明确一点：ContextVar 不是线程局部变量的简单替代品。它把值绑定到当前 Context；asyncio 的任务会维护自己的上下文，而线程执行入口是否复制这份 Context，需要看具体 API 的实现。

二、本机对照实验：三种调用方式得到三个结果

实验环境固定为 Windows 11 10.0.26200、Python 3.13.13。脚本只使用标准库，不访问网络，也不依赖 Web 框架。它分别测试 asyncio.to_thread、run_in_executor 原生调用，以及显式 copy_context 后再提交线程池。

核心代码如下：

import asyncio
import concurrent.futures
import contextvars

request_id = contextvars.ContextVar("request_id", default="MISSING")

def read_request_id():
    return request_id.get()

async def main():
    request_id.set("req-20261107-01")
    loop = asyncio.get_running_loop()

    with concurrent.futures.ThreadPoolExecutor(max_workers=2) as pool:
        via_to_thread = await asyncio.to_thread(read_request_id)
        via_executor = await loop.run_in_executor(
            pool, read_request_id
        )

        ctx = contextvars.copy_context()
        via_copied_context = await loop.run_in_executor(
            pool, ctx.run, read_request_id
        )

    print(via_to_thread)
    print(via_executor)
    print(via_copied_context)

asyncio.run(main())

在本机实际运行，三个结果依次为：

req-20261107-01
MISSING
req-20261107-01

这不是线程池随机选中了不同线程造成的。实验使用同一份 ContextVar、同一个请求标识和同一个 ThreadPoolExecutor；唯一变化是提交任务时有没有把当前 Context 包起来。

我又把实验扩展到工作线程内修改变量、延迟 await，以及可变对象共享。完整脚本在 Python 3.13.13 上实际运行，关键输出如下：

asyncio_to_thread: req-20261107-01
run_in_executor: MISSING
run_in_executor_copy_context: req-20261107-01
caller_context_after_worker_write: req-20261107-01
to_thread_context_when_coroutine_is_awaited: await-context
to_thread_context_inside_created_task: task-created-context
mutable_value_shared_by_reference: 2

所以需要解决的不是"线程池能不能读取 ContextVar"，而是调用入口有没有显式传播 Context，以及传播的具体时机和隔离范围。

三、源码差异：to_thread 多做了两步

Python 3.13 的 asyncio.to_thread 实现非常直接。它先取得当前运行循环，再调用 contextvars.copy_context() 复制当前上下文，然后把真正的函数包装成 ctx.run，最后才交给 run_in_executor：

ctx = contextvars.copy_context()
func_call = functools.partial(ctx.run, func, *args, **kwargs)
return await loop.run_in_executor(None, func_call)

关键就在中间这层包装。工作线程执行的不是原始 func，而是 ctx.run(func)。因此，当前 Context 中已经设置的 request_id 会随这次调用进入线程。

再看 BaseEventLoop.run_in_executor。它的核心路径是 executor.submit(func, *args)，没有自动调用 copy_context，也没有把当前 Context 包装到 func 上。它只负责把给定函数和参数提交给执行器，不负责替调用方决定哪些上下文变量需要传过去。

因此，两种 API 的职责不同：

• asyncio.to_thread：面向同步阻塞函数的便捷入口，自动复制当前 Context，再在线程中运行。
• loop.run_in_executor：更底层的执行器接口，允许指定执行器，但不会替你自动传播 Context。
• copy_context().run：由调用方明确决定把哪一份 Context 带进线程。

这不是 Python 3.13 才临时出现的行为。官方文档对 to_thread 的说明明确写了当前 contextvars.Context 会被传播；run_in_executor 的接口则保持通用执行器提交语义。判断行为时应以所用 Python 版本的官方文档和对应源码为准，不要根据两个函数名字相似就推断它们具有相同的上下文语义。

源码位置也可以直接核对：

• asyncio.to_thread：github.com/python/cpyt...
• run_in_executor：github.com/python/cpyt...
• asyncio 官方任务文档：docs.python.org/3.13/librar...

四、怎么选：不要为了统一写法牺牲上下文语义

如果只是把一个同步阻塞函数放到默认线程池，优先考虑 asyncio.to_thread。它减少了手工传播上下文的代码，也更容易让调用方读懂。

如果业务必须使用自定义 ThreadPoolExecutor，例如要隔离不同类型的阻塞任务、设置独立线程数量或管理执行器生命周期，就可以使用 run_in_executor，但要显式复制 Context。

使用场景	推荐入口	ContextVar 是否自动传播	需要注意
普通同步函数、默认线程池	asyncio.to_thread	是	使用当前任务执行时的 Context
自定义线程池	run_in_executor + copy_context	否，需手动	每次提交创建独立 Context
只传递少量业务字段	显式函数参数	不依赖 Context	参数来源和调用边界清晰
ProcessPoolExecutor	显式传递可序列化字段	不自动传播	不要把 Context 当作进程间载荷
工作线程再创建新线程	在线程边界再次复制	不自动继承	每一次线程切换都要确认上下文

自定义线程池的写法可以这样封装：

import asyncio
import contextvars
from concurrent.futures import ThreadPoolExecutor

async def run_in_context(pool, func, *args):
    ctx = contextvars.copy_context()
    loop = asyncio.get_running_loop()
    return await loop.run_in_executor(
        pool, ctx.run, func, *args
    )

async def main():
    with ThreadPoolExecutor(max_workers=8) as pool:
        result = await run_in_context(
            pool, read_request_id
        )
        print(result)

这里有一个细节不能省略：每次提交任务都创建新的 Context。不要把同一个 ctx 长期保存在全局变量里，再让多个线程同时调用 ctx.run。一个 Context 不能在多个线程中被同时进入；复用同一份上下文可能触发 RuntimeError，也会让任务边界变得难以理解。

如果只是传递 request_id 这样的单个值，也可以直接把它作为函数参数传给线程任务。显式参数更容易测试和审计；ContextVar 更适合大量调用链都需要读取、但又不希望每层函数都增加参数的场景。两者不是谁绝对更好，而是隐式上下文与显式依赖之间的取舍。

五、复制上下文的时机：创建协程不等于立即复制

另一个细节是 asyncio.to_thread 本身是 async 函数。调用它时，得到的是一个协程对象；函数体要等到协程真正开始执行才会运行。

这意味着下面两行之间修改 ContextVar，最终传入线程的值可能是修改后的值：

request_id.set("created-context")
pending = asyncio.to_thread(read_request_id)

request_id.set("await-context")
result = await pending
print(result)

本机实测结果是 await-context。原因不是 to_thread 忽略了第一次设置，而是创建协程对象并没有立即执行函数体。等到 await pending 时，to_thread 才调用 copy_context()，复制的是当时正在执行这个协程的上下文。

如果先把协程包装成 Task，语义又会不同：

request_id.set("task-created-context")
task = asyncio.create_task(
    asyncio.to_thread(read_request_id)
)
request_id.set("caller-changed-after-create-task")

result = await task
print(result)

本机结果是 task-created-context。asyncio.create_task 创建任务时会复制当前任务上下文；随后 to_thread 在新 Task 的上下文里运行，再把这份上下文复制给工作线程。

因此，遇到"为什么线程里读到旧值或新值"的问题，不能只检查 ContextVar.set 的位置，还要检查协程何时被调度、Task 在什么时候创建，以及真正执行 to_thread 函数体的上下文是哪一份。

这对请求追踪尤其重要。如果一个请求先构造协程，随后修改了请求标识，再把协程交给其他 Task 执行，最终传播的值取决于 Task 的创建和调度边界。不要把"调用了 to_thread 的那一行"直接当成上下文快照发生的时刻。

六、上下文隔离不等于对象深拷贝

ContextVar 的值在工作线程里被重新 set，不会反向改写调用方的 Context。实验中，工作线程把 request_id 设置为 worker-only，返回值确实是 worker-only；但主协程再次读取，仍然是 req-20261107-01。

这说明 copy_context 复制的是 Context 到变量值的绑定关系，不是把所有变量值递归深拷贝一遍。若 ContextVar 保存的是字符串、整数等不可变对象，通常更容易理解；如果保存的是列表、字典或自定义可变对象，情况就不同了。

我在实验中把一个字典放进 ContextVar，再让工作线程修改字典内部的 counter。工作线程执行后，调用方看到的 counter 也变成了 2。原因是两个 Context 中的变量绑定虽然分开，但它们仍然指向同一个字典对象。

因此，不要把 ContextVar 当作线程之间的深拷贝隔离机制。适合放入其中的通常是请求 ID、租户 ID、追踪标识、日志标签等轻量上下文值。若需要在不同线程间传递可变业务状态，应使用明确的数据复制、线程安全队列、锁或其他同步方案，并把共享边界写清楚。

还有一个反方向的误区：线程里 set 了新的 ContextVar 值，不代表主协程会自动收到这个新值。如果业务确实需要线程计算结果回传，应通过函数返回值、Future 结果或显式消息传递，不要期待 Context 的修改反向合并。

七、进程池和嵌套线程：传播边界不能想当然

本文的实验对象是 ThreadPoolExecutor。线程共享同一个进程地址空间，Context 可以通过 ctx.run 在工作线程里运行。ProcessPoolExecutor 则不同：任务要跨进程序列化，不能把当前 Context 当作普通 Python 对象直接塞过去。

如果进程池任务需要 request_id、tenant_id 或 trace_id，建议在提交任务时提取真正需要的字段，并作为普通参数传入。这样数据结构清楚，也更容易满足序列化要求。不要为了复用线程池封装，把 Context 传播逻辑原样搬到进程池。

嵌套线程也是类似问题。to_thread 只负责把当前 Context 带到它启动的那次工作线程调用中；如果这个同步函数内部又自行创建一个新的 threading.Thread，新线程不会因为父工作线程曾经运行在复制后的 Context 中，就自动继承同一份上下文。每经过一个新的并发边界，都应重新确认传播方式。

此外，ContextVar 的默认值只解决"当前 Context 没有设置变量时返回什么"，并不能证明请求上下文已经正确传播。如果默认值是空字符串、None 或一个看似正常的匿名租户，丢失上下文可能不会抛异常，只会让数据被错误归类。对关键追踪字段，最好在入口处验证必需值，并在缺失时显式记录错误，而不是用默认值掩盖传播失败。

八、落地结论：按执行边界选择传播方式

如果你的同步函数只需要在默认线程池执行，asyncio.to_thread 是最省心的选择。它自动复制当前 Context，代码也更短。

如果你必须使用自定义线程池，保留 run_in_executor，并在每次提交时调用 contextvars.copy_context()，再通过 ctx.run 执行目标函数。不要共享同一个 Context 给并发任务。

如果只需要一两个字段，显式参数通常更清楚；如果需要进程池或跨服务传播，就把上下文转换成可序列化的业务数据，而不是传递 Context 对象。

最后还要记住两个边界：Context 的复制不是对象深拷贝，线程内部 set 的新值也不会自动回写调用方。把这两点纳入测试，才能避免"日志看起来有 request_id，实际却串了请求"这类更难排查的问题。

如果你在自定义线程池里维护链路追踪，更倾向于每次提交都用 copy_context 包装，还是把 trace_id 显式作为参数传递？前者改动小、适合已有 ContextVar 体系；后者依赖关系更清晰。你在团队里会把哪一种定为默认规范？

参考资料：

• asyncio.to_thread：docs.python.org/3.13/librar...
• loop.run_in_executor：docs.python.org/3.13/librar...
• contextvars：docs.python.org/3.13/librar...
• CPython 3.13 threads.py：github.com/python/cpyt...
• CPython 3.13 base_events.py：github.com/python/cpyt...