结论先行: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 在哪里