ThreadLocal内存泄漏根源与JDK25 ScopedValue演进

如果你在网上搜 ThreadLocal 相关面试题，大概率会碰到这么一道：“ThreadLocal 明明用了 WeakReference，为什么还会内存泄漏？”我在刚工作那几年也被绕晕过，直到自己上线排查过一次，才算把强引用、弱引用和 ThreadLocalMap 的三角关系彻底理清。到了 JDK25 这个时间点，ScopedValue 的出现又给这个问题提供了另一种解法——它从设计上就不允许你把它泄漏掉。这篇文章不打算背八股，我想从实际开发者的视角，把 ThreadLocal 的内存泄漏讲明白，再把 JDK25 里 ScopedValue 的演进看到底，顺便给还在面试季挣扎的同学一点能直接用的结论。

1. ThreadLocal 到底解决什么问题，为什么会用到它

1.1 从“传参地狱”到线程私有仓库

ThreadLocal 的官方解释是“线程局部变量”，但它本质上做的事非常朴素：给每个线程准备一个独立的存储空间，线程之间互相看不见。这就像每个工位都有自己带锁的抽屉，别人打不开，你自己随时能存取。

用一段最基础的代码看：

java复制private static final ThreadLocal<String> REQUEST_ID = new ThreadLocal<>();

public void handleRequest(String requestId) {
    REQUEST_ID.set(requestId);
    // 后续任何地方都可以通过 REQUEST_ID.get() 拿到当前请求的 ID
    doBiz();
}

public void doBiz() {
    String id = REQUEST_ID.get();
}

在没有 ThreadLocal 之前，这种“当前请求上下文”只能靠方法参数一层层往下传。代码多了之后，你会发现每个方法签名里都要带上 traceId、userId、tenantId 这些八竿子打不着的参数，改了签名下游全部要动，维护成本极高。ThreadLocal 把这个痛点解决了：上下文信息跟线程绑定，业务代码在任意深度都能拿到，不用改方法签名。

1.2 我实际用过的三类场景

第一类是调用链上下文。比如网关进来一个请求，中间经过了 Filter、Interceptor、Service、DAO，每个环节都要记录 traceId，用 ThreadLocal 在入口 set 一次，后面所有地方都能 get。

第二类是框架层面的“事务绑定”。Spring 的 TransactionSynchronizationManager 就是把数据库连接放进 ThreadLocal，保证同一个事务里多次 DAO 操作拿的是同一个 Connection，这是典型的大规模工业级应用。

第三类是线程内复用非线程安全对象。最经典的是 SimpleDateFormat，非线程安全，每次 new 一个成本又高。用 ThreadLocal 给每个线程存一个实例，既不共享、也不用每次创建：

java复制private static final ThreadLocal<SimpleDateFormat> DATE_FORMAT =
        ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd"));

public String format(Date date) {
    return DATE_FORMAT.get().format(date);
}

1.3 面试官真正想考的是什么

ThreadLocal 相关的面试题翻来覆去就那么几个：为什么不直接用 Map<Thread, Object>？为什么 key 要用弱引用？为什么用了弱引用还会内存泄漏？InheritableThreadLocal 在线程池里会有什么问题？和 ScopedValue 比有什么优劣？

其实这些问题都指向同一个底层认知：ThreadLocal 的存储结构是线程内部的一个 Map，这个 Map 的 Entry 用弱引用当 key，value 却是强引用。你没把这个结构想清楚，后面所有问题都答不透。这也是我接下来要重点展开的内容。

2. 内存泄漏的根源：强引用、弱引用与 ThreadLocalMap 的三角关系

2.1 一句话讲清 ThreadLocal 的底层存储结构

每个 Thread 对象内部有一个 ThreadLocal.ThreadLocalMap 字段，专门存本线程的 ThreadLocal 值。ThreadLocalMap 的 Entry 继承自 WeakReference<ThreadLocal<?>>：

java复制static class Entry extends WeakReference<ThreadLocal<?>> {
    Object value;

    Entry(ThreadLocal<?> k, Object v) {
        super(k);
        value = v;
    }
}

注意这里的两个引用：

• key（ThreadLocal 对象本身）是弱引用，存放在 WeakReference 内部。
• value（你 set 进去的那个对象）是强引用，直接挂在 Entry 上。

ThreadLocalMap 的 key 是弱引用，意味着只要外部没有强引用指向这个 ThreadLocal 对象，GC 时 key 就会被回收，Entry 的 key 变成 null。但 value 不会自动回收，因为 Entry 自己还活在 ThreadLocalMap 里，而 ThreadLocalMap 还活在 Thread 对象内部。

2.2 为什么“弱引用 key”反而制造了经典的泄漏

很多人以为弱引用是防内存泄漏的，实际上 WeakReference 只解决了“ThreadLocal 对象自身无法回收”的问题，没解决“value 无法回收”的问题。

举个具体例子。你在一个请求入口做了：

java复制ThreadLocal<byte[]> holder = new ThreadLocal<>();
holder.set(new byte[1024 * 1024 * 10]); // 10MB

请求结束后，holder 这个局部变量离开作用域，外部指向 ThreadLocal 对象的强引用没了。此时：

1. GC 时 ThreadLocalMap 里的 key（弱引用）会被回收，key 变成 null。
2. 但 value 是一个 10MB 的 byte[]，它是强引用，挂在 Entry 上。
3. Entry 又在 ThreadLocalMap 里，ThreadLocalMap 又绑在 Thread 上。

如果当前线程是一个普通业务线程，请求处理完线程就销毁，那整个链一起被回收，问题不大。但如果当前线程来自线程池，线程是复用的，长时间存活，那这个 10MB 的 byte[] 就会一直挂在老年代里，直到线程池关闭。这就是内存泄漏。

2.3 弱引用到底防住了什么、又没防住什么

这里我想用一个生活化的类比：把 ThreadLocalMap 想成宿舍楼里的储物柜，ThreadLocal 对象是钥匙，value 是柜子里的书。

如果你的钥匙被扔了，但书还锁在柜子里，柜子没人打开，书就永远卡在里面。弱引用就是“钥匙被扔了”这件事——ThreadLocal 对象本身可以被回收了；但“书还锁在柜子里”这件事没人管，因为 ThreadLocalMap 的 Entry 还活着。

JDK 设计者不是没做补救。ThreadLocalMap 在 get、set、remove 时会顺带做一次 expungeStaleEntry 探测清理，把 key 为 null 的 Entry 清掉。坏就坏在“顺带”两个字：如果这个线程之后再也没有访问过这个 ThreadLocal，也没有向 ThreadLocalMap 写入新的键值对，那这些脏 Entry 就永远没有机会被清理。

所以 ThreadLocal 内存泄漏的真正成因可以总结成一句话：线程长期存活 + 弱引用 key 被回收但 value 未清理 + 没有后续访问触发探测清理。

2.4 面试题里常考的几个衍生结论

理解了这个三角关系，很多衍生问题直接用逻辑推就能出来：

• 为什么 ThreadLocal 用在简单业务线程里很少泄漏？因为线程用一次就销毁，ThreadLocalMap 跟着销毁。
• 为什么线程池 + ThreadLocal 是重灾区？因为线程存活时间长，脏 Entry 会一直积累。
• 为什么 Alibaba 规范强制要求 ThreadLocal 必须 remove？因为它防的是线程池复用场景下的“脏数据 + 泄漏”组合拳。
• 为什么 key 不用强引用？因为如果 key 是强引用，ThreadLocal 对象即使外部已经没人用了，也会被 ThreadLocalMap 强持有，无法回收，情况更糟。弱引用至少保证了 key 本身能被回收。

要说这个设计是完美的，那肯定不是。它更像一种“两害相权取其轻”的取舍：你想让 ThreadLocal 对象能回收，想让用户显式管理 value 的生命周期，那就用弱引用做 key，同时寄希望于用户能养成 remove 的习惯。可惜现实里，能严格遵守 remove 的项目真不多。

3. 一场真实排查：从 heap dump 到确认 ThreadLocal 泄漏的完整链路

3.1 现场症状：接口偶发超时与内存占比异常

我之前接手过一个线上服务，症状很典型：服务运行一周后 Old 区占比持续升高，GC 时间越来越长，接口偶发超时。重启之后能好两三天，然后又开始恶化。这种“重启就好、越跑越差”的现象，十有八九跟缓存或线程局部引用有关。

首先需要区分是缓存还是线程泄漏。我用 jstat -gcutil <pid> 观察，发现 Old 区利用率曲线一路向上，没有回落趋势，说明有对象被长期锚定。再看 jmap -histo:live <pid>，排序靠前的是 byte[] 和 Object[]，数量不算特别惊人，但大对象不少。

有同行问能不能用 WinDbg 检测这类内存泄漏。WinDbg 是 Windows 平台上分析 native 内存、死锁和堆栈的利器，但 JVM 堆内对象它不是最佳选择。对 JVM 场景，我更推荐配合 jmap 抓堆转储，然后用 Eclipse MAT 分析。WinDbg 在这个问题上属于“能用但被绕远路”的工具。

3.2 用 jmap 和 MAT 顺藤摸瓜

我当时的操作链路是这样的：

bash复制jmap -dump:live,format=b,file=heap.hprof <pid>

然后用 MAT 打开 heap.hprof，先看 Dominator Tree，按 Retained Heap 排序，马上看到几个大对象被同一个线程池线程持有。用 MAT 的 “Path to GC Roots” 功能一查，引用链非常清晰：

code复制Thread
 └── ThreadLocal.ThreadLocalMap
      └── Entry
           └── value (byte[])

这说明 value 是被 ThreadLocalMap 锚住的，而且这些 Entry 来自线程池里长期存活的线程，这是 ThreadLocal 泄漏的典型标记。

接下来要判断 key 是否已经变成 null。如果 key 是 null，说明外部强引用早就没了，纯粹是“忘了 remove”导致的脏 Entry。如果 key 不是 null，说明那个 ThreadLocal 对象还活着，但 value 一直在堆里堆积，要么是业务往里面放了太多东西，要么是 set 了之后就没有更新和清理，这种也值得注意。

3.3 顺着引用链找到业务代码

MAT 里能看到 entry 的 value 类型和实际对象内容。我那次看到的 value 是某个业务对象的序列化副本，字符串里带着租户 ID。反向一搜，确认是网关层在拦截器里 set 了租户上下文，处理完没有 remove，线程池复用后，每个线程第一次处理请求时塞进去的租户信息就一直留在内存里。

这也是 ThreadLocal 泄漏里比较隐蔽的一种：它不是单纯把值泄漏了，而是把“某个用户的数据”泄漏给了后面所有复用的请求。这已经不是性能问题了，是数据安全问题。

这里我给出一个排查经验总结：

4. remove() 的正确姿势：线程池场景下的双保险

4.1 为什么 finally + remove() 不是可选项

修复 ThreadLocal 泄漏最直接的方式，就是在 finally 里 remove。这条规则写在我见过的大部分 Java 开发规范里，但它在代码评审中依然反复被忽略。

原因可能在于：很多人在单测或者简单 Demo 里跑 ThreadLocal，线程用完就销毁了，泄漏不表现出来，就觉得 remove 可有可无。但生产环境一旦上了线程池，脏数据会以“延迟爆发”的方式出现，你很难在测试阶段复现。

正确写法长这样：

java复制ThreadLocal<String> CONTEXT = new ThreadLocal<>();

public void process(String value) {
    CONTEXT.set(value);
    try {
        doSomething();
    } finally {
        CONTEXT.remove();
    }
}

为什么一定是 finally，不能是 try 末尾 remove？因为 try 块里一旦抛出异常，末尾的 remove 根本不会执行。finally 保证无论正常返回还是异常抛出让线程回归池子，上下文都被清干净。

4.2 线程池复用时，不只是泄漏还有串数据

ThreadLocal 在线程池里还有一个更隐蔽的问题：数据串线。

举个例子：

java复制ExecutorService pool = Executors.newFixedThreadPool(2);
ThreadLocal<String> USER = new ThreadLocal<>();

pool.execute(() -> {
    USER.set("张三");
    // 业务处理，期间抛了异常，没走到 remove
});

Thread.sleep(100);
pool.execute(() -> {
    String user = USER.get();
    // 到这里，user 很可能还是 "张三"
});

第二个任务根本不属于张三，却读到了张三的上下文。如果这个 context 是用户 ID、租户 ID、权限标识，后果就是越权访问或者把数据写错归属。

这种串数据问题比内存泄漏更危险，因为内存泄漏最终会表现为监控告警，而串数据可能默默产生错误的业务结果。排查起来还特别费劲，因为它是偶发的，跟线程池任务调度顺序和异常时间点强相关。

4.3 如果你觉得 finally 太丑，可以封装一个自动清理的壳

我自己在实际项目里经常写一个小的工具类，把 set + try + finally + remove 包成一个函数，避免每个调用点都手写一遍：

java复制public final class ThreadLocalSupport {
    private ThreadLocalSupport() {}

    public static <T> void bind(ThreadLocal<T> threadLocal, T value, Runnable action) {
        T oldValue = threadLocal.get();
        threadLocal.set(value);
        try {
            action.run();
        } finally {
            if (oldValue == null) {
                threadLocal.remove();
            } else {
                threadLocal.set(oldValue);
            }
        }
    }
}

调用方只需要：

java复制ThreadLocalSupport.bind(USER_CONTEXT, user, () -> {
    businessService.doBiz();
});

这样 bind 退出时一定会恢复原来的值或清理掉临时值，比每个方法里手写 try/finally 少犯错。另外再提醒一句，InheritableThreadLocal 在线程池里尤其危险：它只在线程创建时把父线程的值复制给子线程一次，线程池复用了线程之后，新提交的任务并不会重新从父线程复制值，而是沿用旧值。这个坑在面试里也会被问到，我的回答永远是：线程池场景下别用 InheritableThreadLocal。

5. ScopedValue 的登场：JDK25 中它带来了什么

5.1 ThreadLocal 的固有缺陷，换个角度解

ThreadLocal 的根问题在于“生命周期跟线程绑定”，而不是跟业务作用域绑定。一旦线程被池化，ThreadLocal 的生命周期就被无限拉长了，你不得不用 remove 去手动截断。这种手动管理导致的问题，在虚拟线程时代会更加明显——虚拟线程本身很轻，但 ThreadLocal 会随身携带一个 Map，线程多了之后这些 Map 的内存开销会非常可观。

JDK 的应对方案就是 ScopedValue。它的核心思路是：把值的生命周期跟一个动态作用域绑定，而不是跟线程绑定。作用域结束，值自动消失，不需要手动清理，也没有“脏值残留”的可能。

ScopedValue 最早以孵化模块的形式进入 JDK 22，后续版本里 API 持续稳定迭代，到了 JDK 25 这个版本，你在代码里写 ScopedValue 基本就是下面这个样子了。不同发行版如果还处于孵化期，需要在启动参数里打开对应的模块开关；如果已经转正，直接导入 java.lang 就能用。我建议你以自己实际环境的编译报错为准，但核心用法是一致的。

5.2 不会泄漏的核心机制：不可变 + 作用域自动结束

ScopedValue 的使用方式和 ThreadLocal 有相似之处，但改动了一个关键设计：

java复制private static final ScopedValue<String> REQUEST_ID = ScopedValue.newInstance();

public void handleRequest(String requestId) {
    ScopedValue.where(REQUEST_ID, requestId, () -> {
        // 在这个 lambda 作用域内，REQUEST_ID.get() 能拿到 requestId
        System.out.println(REQUEST_ID.get());
    });
    // 离开这个 lambda 之后，REQUEST_ID 在“当前线程”就不再绑定
}

第一眼看上去，这不就是 ThreadLocal 换了个写法吗？差别可大了：

• ScopedValue 绑定的是一个动态作用域，lambda 执行完，绑定自动失效。
• 它没有 set() 方法，你不能在作用域中间偷偷改值。
• 要改变当前值，只能嵌套一层新的 where，形成一个新的不可变快照。
• 它从根本上消灭了“线程复用后值残留”的问题。

不可变性是这个设计的关键。ThreadLocal 允许你在代码任何地方 set 一个新值，等于给了每个线程一块可以随手改写的全局画板。ScopedValue 则把值固化成“当前调用链上的一个上下文快照”，你想要新值，就新建一个作用域，而不是修改共享状态。

5.3 和虚拟线程、结构化并发配合的典型写法

ScopedValue 和虚拟线程是配套推出的设计。它的传播是靠调用链，不是靠线程复制的。配合 StructuredTaskScope，你可以把上下文传递给并发的子任务，而不需要像 InheritableThreadLocal 那样在创建线程时复制：

java复制private static final ScopedValue<String> USER = ScopedValue.newInstance();

public void handle(String userId) throws Exception {
    ScopedValue.where(USER, userId, () -> {
        try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
            Future<Account> account = scope.fork(() -> accountService.get(USER.get()));
            Future<List<Order>> orders = scope.fork(() -> orderService.list(USER.get()));
            scope.join();
            scope.throwIfFailed();
            // 拿到并发结果，继续处理
        }
    });
}

在这里，子任务里 USER.get() 能取到外层 where 绑定的值，是因为任务是在这个作用域内创建的，运行时会把绑定快照一起带过去。父任务作用域结束后，这个快照就不可见了，连回收都不用操心。对比 ThreadLocal 在线程池里的表现，这个设计干净得让人舒服。

6. 从 ThreadLocal 迁移到 ScopedValue：收益、成本与实操建议

6.1 两个方案的全面对比

6.2 哪些场景值得迁移，哪些场景继续用 ThreadLocal

先说我的结论：新代码里，请求级上下文、用户身份、traceId 这类“进入请求时确定、请求期间只读”的上下文，直接优先用 ScopedValue。你不需要在 finally 里 remove，不需要担心线程池脏数据，传参也省了。

但有几个场景我建议先别动：

第一个是框架底层实现。比如事务管理器绑定数据库连接，这类代码大量依赖“同一个线程内多次调用拿到同一个值”的语义，而且框架本身已经通过 ThreadLocal 封装好了生命周期，迁移成本高、收益低。这种事留给框架作者去决策。

第二个是需要在运行中途修改上下文的场景。ScopedValue 没有 set()，你想在业务中间改一次用户级别，必须嵌套一个新的 where 作用域，这会让代码结构变得别扭。如果业务上频繁修改上下文，ThreadLocal 反而更顺手。

第三个是和老代码共存的问题。如果项目里大量代码依赖 ThreadLocal，你直接把局部逻辑切到 ScopedValue，很可能出现“入口用 ScopedValue 绑定了，但底层老代码还在从 ThreadLocal 里读”的割裂。这种混合状态很容易出线上事故，迁移前先把边界理清楚。

6.3 迁移中的常见坑

我实际折腾过几次后，总结出三个最常见的坑。

第一个坑：把 ScopedValue.get() 放进异步回调或者延迟执行的任务里。比如你在 where 作用域里提交了一个任务到另一个线程池，任务在作用域结束后才异步执行，这时 get() 会抛异常。因为绑定是跟着调用链走的，不是跟着任意线程走的。解决方案是把值在进入异步边界之前显式取出，作为参数传递，或者确保读取发生在作用域内。

第二个坑：试图把 ThreadLocal 和 ScopedValue 混在一个上下文对象里。比如你写了一个 CurrentContext 类，内部既用 ThreadLocal 存 userId，又想用 ScopedValue 存 traceId，这种混合会让排查问题的时候非常崩溃。我的建议是，一个上下文类只选一种存储机制，不要混搭。

第三个坑：低估了不可变性的改造量。很多现有业务代码会在请求中途做 context.set(user) 更新当前用户，这是 ThreadLocal 的常规操作，但 ScopedValue 不支持。切换前需要重构出“作用域入口就确定用户”的代码结构，这往往比想象中费劲。所以我的迁移策略是：新模块、新接口直接用 ScopedValue；老模块如果 ThreadLocal 用得好好的，没有泄漏告警，就没必要为了追新而大动干戈，先把 finally { remove(); } 这个底线守住。

从 ThreadLocal 到 ScopedValue，本质上是从“线程承载状态”向“调用作用域承载状态”演进。前者把清理责任抛给开发者，后者把生命周期锁死在语言机制里。对我个人来说，写代码的时候最舒服的永远是“不用记得清理”的机制。如果你现在正准备在新项目里搭上下文传递方案，我是建议直接按 ScopedValue 的路子来；跑完上面几个示例代码，你大概也会认同这个方向。