结论先行:ThreadLocal 内存泄漏的直接原因是 value 的强引用链——ThreadLocalMap 的 key 是弱引用,value 却是强引用;只要线程不死(线程池复用正是如此),value 就一直被拽着回收不掉。解法只有一个:用完在 finally 里 remove。至于「弱引用为什么还会泄漏」,要进到 Map 的结构里看。

引用链长什么样

每个 Thread 内部有一个 ThreadLocalMap,Entry 的定义是关键:

static class Entry extends WeakReference<ThreadLocal<?>> {
    Object value;
    Entry(ThreadLocal<?> k, Object v) {
        super(k);      // key 是弱引用
        value = v;     // value 是强引用
    }
}

完整引用链:Thread → ThreadLocalMap → Entry → value(强引用);Thread → ThreadLocalMap → Entry → key(弱引用)。当外部对 ThreadLocal 对象的引用消失后,key 在下次 GC 被回收变成 null,但 value 依然被 Entry 强引用着——这个 Entry 就是所谓的 stale entry,value 成了不可达却回收不掉的对象。注意方向性:是 Thread 持有 Map,不是 ThreadLocal 持有——「多个线程用同一个 ThreadLocal」时,每个线程各自的 Map 里都有一份自己的 value;「一个线程用多个 ThreadLocal」时,它们共存在这个线程的 Map 里,以 ThreadLocal 对象为 key 散列存储。

Map 的散列实现也有讲究:key 的 hash 用魔数 0x61c88647(黄金分割数)步进散列,能让多个 ThreadLocal 的槽位均匀散开、基本不碰撞;表长是 2 的幂。魔数散列的前提是「一个线程内的 ThreadLocal 数量有限」,这也解释了这个 Map 为什么不做树化兜底——碰撞场景按设计不会出现。

为什么 key 设计成弱引用

如果 key 也是强引用,业务代码里的 ThreadLocal 引用没了,Map 里还留着它,ThreadLocal 对象本身也泄漏了。弱引用至少保证 key 能被回收,JDK 还做了兜底:调用 set/get/remove 时会顺带清理 key 为 null 的 stale entry(expungeStaleEntry)。但兜底是机会主义的——你不调用这些方法,清理就不会发生,而线程池里的线程可能几个月都在接任务;get 路径的清理只发生在哈希到同一槽位附近时,覆盖不了全表,唯一彻底的清理入口是 remove。所以官方文档的口径一直很明确:ThreadLocal 的正确生命周期就是 set → 使用 → remove 三段式,弱引用只是缓解,不是保证。

验证可以做个对照实验:起一个线程池线程,set 一个大对象后不 remove,用 jmap -histo:live 观察这个对象在多次 Full GC 后依然存在;补上 remove 后立刻消失。十分钟就能做完,适合作为团队内的科普材料——比一百句「要记得 remove」都有说服力。

真正的元凶是线程池

单次请求场景,Thread 执行完销毁,Map 整个被回收,谈不上泄漏。线上泄漏几乎都发生在 Tomcat 工作线程、业务线程池这类常驻线程上:线程存活几小时到几十天,塞进去的 value(往往还不小,比如整个用户上下文对象)一直占着内存。更隐蔽的是「串数据」——下一个请求复用这个线程,读到了上一个请求 set 的用户信息,这是比内存占用更严重的安全问题。内存泄漏还能靠加堆续命,串数据直接就是线上事故。两类问题同源:线程活着,Map 就活着;Map 活着,没清的 entry 就都在。

内存规模感也要建立:一个存完整用户上下文(含权限列表、会话数据)的 value 按 2KB 估算,200 个常驻线程再乘以多个 ThreadLocal 字段,泄漏量轻松到几十 MB——单看不大,但它不释放,还会随着 ThreadLocal 字段增多线性放大,堆监控上表现为「稳定抬升的基线」,正是这类趋势比单次毛刺更值得告警。

排查也有捷径可记:怀疑 ThreadLocal 泄漏时,dump 里统计 ThreadLocalMap$Entry 的实例数和 key 为 null 的 stale entry 占比,不用猜就能量化严重程度,还能顺藤摸瓜看 value 里装的是什么对象,这两个数字值得直接写进内存监控看板。

标准写法与三条纪律

private static final ThreadLocal<UserContext> CTX = new ThreadLocal<>();

public void handle(Request req) {
    CTX.set(parseUser(req));
    try {
        doBusiness();          // 业务链路上任何一层都可以 CTX.get()
    } finally {
        CTX.remove();          // 与 set 严格配对,线程归还前清干净
    }
}

三条纪律:声明为 private static final(避免 ThreadLocal 对象本身被提前回收产生 stale entry);set 与 remove 严格配对,remove 放 finally;拦截器/Filter 场景在 afterCompletion 里统一清理。第三条容易被遗漏的变体是异步任务:主线程 set 之后 submit 到线程池的任务里读不到值,有人就在子任务里再 set 一次——子任务结束又不清,泄漏面反而扩大:

// 错误写法:在子任务里各自 set,从不 remove
pool.submit(() -> {
    CTX.set(fallbackUser());   // 子线程的 Map 里从此躺着一份 value
    audit();                   // 任务结束没有任何清理
});

// 正确写法:上下文作为参数显式传入,子任务不碰 ThreadLocal
UserContext user = CTX.get();
pool.submit(() -> audit(user));    // user 是局部变量,任务结束即可回收

另有一个历史场景要澄清:早年用 ThreadLocal 包装 SimpleDateFormat 解决线程安全问题,JDK 8 之后应直接用 DateTimeFormatter(不可变,天然线程安全)——为不可变工具类维护 ThreadLocal 已没有必要,少一个 ThreadLocal 就少一份清理责任。

跨线程传递的方案选择

「主线程 set、池中线程取不到」的传递问题有专门方案。InheritableThreadLocal 只在创建子线程那一刻复制父线程的值,线程池的线程是复用的,复制时机根本不在提交任务时,所以线程池下基本不可用。事实上的标准是阿里的 TransmittableThreadLocal(TTL):提交任务时抓取快照,任务执行前回放、执行后恢复,配合 TtlExecutors 包装线程池即可。方案取舍见下表:

方案线程池下可用性原理适用场景
ThreadLocal不可传递每线程一份 Map单线程内传递上下文
InheritableThreadLocal基本不可用仅在 new Thread 时复制一次性短命子线程
TransmittableThreadLocal可用提交时快照、执行时回放线程池上下文透传
显式参数传递可用上下文作方法参数不想引入依赖、链路短

选择建议:链路短、调用点少时直接显式传参,最简单也最好测试;调用层级深、中间层不该感知上下文(鉴权、traceId)时上 TTL。不要为了省一个参数把上下文塞进 ThreadLocal 再配一堆清理代码——能用参数表达的依赖,不要藏在隐式状态里。

无论哪种方案,remove 的纪律都一样:谁 set 谁 remove,线程归还前必须干净。

生产案例

某次线上事故:用户反馈登录自己账号后,页面偶尔显示另一个用户的订单摘要。排查链路(网关 → 用户上下文解析 Filter → 业务线程池)后发现,上下文 Filter 的 afterCompletion 里没有调用 remove,而某次重构把一段鉴权逻辑挪进了线程池异步任务,任务里读了 ThreadLocal 的用户身份做审计埋点。两个缺陷叠加:Filter 不清理让 value 残留,异步任务在某些分支还额外 set 了一份;下一个请求复用该线程时,若解析逻辑因异常提前返回,业务代码读到的就是上一个请求的残值。修复本身很小——Filter 统一清理、异步任务改显式传参——但事故级别不低。这类问题的可怕之处在于复现依赖「特定线程恰好被特定顺序复用」,测试环境几乎撞不出来,只能靠纪律保证:所有 ThreadLocal 的 set 都要能回答「谁在哪儿 remove」。

配套的工具支撑也值得建设:提供统一的上下文组件,把 set/remove 的生命周期封装进去,替代散落在各处的裸 ThreadLocal——让「忘记 remove」从个体失误变成结构上不可能。架构上也因此规定:用户上下文只允许通过统一入口访问,业务代码禁止直接持有 ThreadLocal 引用,封装点的评审成本远低于全量评审。

检查清单

  • ThreadLocal 声明为 private static final
  • set 与 remove 严格配对,remove 放 finally 或 afterCompletion
  • 异步任务不在线程池线程里 set,上下文显式传参
  • 线程池跨线程透传用 TransmittableThreadLocal + 包装执行器
  • 不用 InheritableThreadLocal 解决线程池传递
  • 存入 value 保持最小体积(存 ID 不存整个大对象)
  • 用户身份类上下文每次请求强制覆盖,拒绝读取残值
  • 代码评审固定问题:这个 set 对应的 remove 在哪里