前阵子处理一个线上告警服务的堆内存每过几天就往上爬一截老年代 GC 之后也压不回去最后只能分批重启节点。翻 heap dump 的时候我在线程池那几个长期存活的工作线程上看到一堆本该早就死掉的对象根就是ThreadLocalMap里的某个 Entry。说实话ThreadLocal的 API 简单到三分钟能上手但把它的底层结构、弱引用机制和线程池的复用特性放在一起看就是一个典型的“越简单越容易埋雷”的案例。这篇文章我会把ThreadLocal从原理到实战整个链条重新捋一遍Thread对象里的ThreadLocalMap到底怎么存数据、Entry 的弱引用设计为什么会成为内存泄漏的温床、生产环境里哪些写法一定会出问题以及真出问题后怎么一步步复现、抓堆、定位到代码行。适合刚接触ThreadLocal想深入研究源码的人也适合正在被线上内存问题折磨的同学直接照着排查思路走一遍。先说结论免得看到中间被吓到ThreadLocal本身没有错坑几乎都出在“长命线程 不清理”这六个字上。1. 从 SimpleDateFormat 说起ThreadLocal 的定位与适用边界1.1 一个最经典的切入案例非线程安全的日期格式化很多人在项目里第一次用ThreadLocal是因为SimpleDateFormat。SimpleDateFormat的parse和format内部维护了一个Calendar对象多线程共享同一个实例时Calendar的状态会被互相覆盖轻则日期格式错乱重则直接抛异常。早期 Java 老项目最常见的修法就是给整个方法加synchronized代价是同一时刻只有一个线程能格式化日期后来有人把SimpleDateFormat塞进ThreadLocal每个线程持有自己的实例互不干扰性能也回来了。用代码写出来非常直观private static final ThreadLocalSimpleDateFormat DATE_FORMAT ThreadLocal.withInitial(() - new SimpleDateFormat(yyyy-MM-dd HH:mm:ss)); public String format(Date date) { return DATE_FORMAT.get().format(date); }withInitial是 Java 8 之后推荐的写法它懒初始化只有当前线程第一次get时才调用工厂方法创建副本。在线程池场景下每个工作线程也只会创建一份不会像在方法内部new那样每调用一次就创建一个对象。ThreadLocal的本质是“每个线程一个独立副本”而不是“对象本身变安全了”。它适合两类场景一是让非线程安全对象在每个线程内独享二是在调用链中传递隐式上下文登录用户、TraceId、租户信息避免一路加参数。1.2 适用范围与两个常见误解ThreadLocal不是万能的。它解决不了“线程间需要实时共享数据”的问题也不是用来替代方法参数的公共垃圾桶。我见过有人把几十 MB 的查询结果塞进ThreadLocal当作“缓存”这种用法基本是给自己挖坑。这里有两个常见误解必须先澄清ThreadLocal不是“每个ThreadLocal实例维护一个全局 Map”而是每个Thread对象身上挂一张ThreadLocalMap里面可以存多个ThreadLocal键值对。get返回的是当前线程的副本换一个线程调用get拿到的是另一个线程各自初始化好的对象绝对不会串数据——前提是别在同一个线程里把上下文当全局变量用。这第二个误解引出的问题很关键ThreadLocal在线程池里容易出事的根源恰恰是“线程不销毁副本就一直在”。你看着是一次请求处理完了但对线程池里那个线程来说它的ThreadLocal副本还挂在身上什么时候被清理全看有没有人主动remove。2. 底层结构拆解ThreadLocalMap、弱引用 Entry 与黄金分割哈希2.1 数据到底存哪了Thread 类上的两个字段很多人以为ThreadLocal内部有个 Map 存所有线程的数据这是最大的误解。真相在Thread类源码里public class Thread implements Runnable { ThreadLocal.ThreadLocalMap threadLocals null; ThreadLocal.ThreadLocalMap inheritableThreadLocals null; }每个Thread对象天生带了两个ThreadLocalMap引用默认都是 null。调用set时内部先拿到当前线程t再取t.threadLocals为空就new一个不为空就调用map.set。所以数据从来不是存在ThreadLocal实例里而是存在当前线程自己的属性里。ThreadLocal实例在这里只扮演 key 的角色。这个设计最大的好处是隔离性天然成立访问完全不需要加锁每个线程读写的都是自己的 Map。代价也很明显——Map 的生命周期和线程绑定。普通线程结束Thread对象不可达整张表跟着被回收但线程池里的核心线程不会结束这张表就会一直陪着线程活到应用停掉。2.2 Entry 的内部结构key 是弱引用value 是强引用ThreadLocalMap的每个节点是Entry定义非常特别static class Entry extends WeakReferenceThreadLocal? { Object value; Entry(ThreadLocal? k, Object v) { super(k); value v; } }Entry继承WeakReference把ThreadLocal作为弱引用目标value 则是普通强引用。为什么要这么设计如果 Entry 强引用 key那么只要线程的 Map 还在所有用过的ThreadLocal实例就永远不会被回收——哪怕业务代码已经不再持有它。用弱引用至少能让 key 有机会跟随 GC 被回收。注意这里只是 key 有机会被回收value 还欠着这个坑我留到第 3 节重点讲。2.3 哈希设计0x61c88647 与开放寻址ThreadLocalMap本质是哈希表但它和HashMap不同没有链表也没有红黑树用的是开放寻址线性探测。每个ThreadLocal实例有一个自增的threadLocalHashCodeprivate final int threadLocalHashCode nextHashCode(); private static AtomicInteger nextHashCode new AtomicInteger(); private static final int HASH_INCREMENT 0x61c88647; private static int nextHashCode() { return nextHashCode.getAndAdd(HASH_INCREMENT); }0x61c88647是斐波那契散列里常用的魔数相当于 2^32 乘以黄金分割比例的小数部分。它保证了连续创建的ThreadLocal实例在哈希表上的下标分布足够均匀线性探测的冲突少。定位下标的公式是int i key.threadLocalHashCode (table.length - 1);因为table.length永远是 2 的幂所以按位与等价于取模但比取模快。这也是为什么ThreadLocalMap初始容量是 16而不是随便一个数。冲突时该怎么办ThreadLocalMap不像HashMap那样在桶后面挂链表而是顺序往后找空位。这就是开放寻址。这个设计有代价数组必须留一定余量所以实际容量一旦超过扩容阈值默认是长度的 2/3就会触发rehash先清掉所有 key 为 null 的陈旧 Entry再决定是否把数组翻倍。2.4 set/get/remove 的执行路径把set的过程拆开看就是一次桶定位加线性探测// 伪代码描述 ThreadLocalMap.set 的核心逻辑 int i key.threadLocalHashCode (table.length - 1); for (Entry e table[i]; e ! null; e table[i nextIndex(i, len)]) { if (e.get() key) { e.value value; // 命中相同 key直接更新 return; } if (e.get() null) { replaceStaleEntry(key, value, i); // 占用 key 已被回收的槽位 return; } } table[i] new Entry(key, value);注意中间那个分支探测过程中如果发现某个槽位 key 为 null说明ThreadLocal已经被 GC就直接复用这个槽顺带做清理。get的路径类似区别是探测时一旦遇到 key 为 null 的槽会调用expungeStaleEntry把它清掉防止 value 一直挂在数组里。remove就一句话从 table 中找到对应 key 的槽把这条 Entry 整体置空key 和 value 的应用同时断开这也是唯一能保证立即释放 value 的方式。读完这部分你应该明白一件事只要线程活着它的ThreadLocalMap就一直存在所谓“线程结束自动清理”依赖的是线程对象整体不可达而不是ThreadLocal做了什么自动清理。3. 内存泄漏根因弱引用为何保住了 key却保不住 value3.1 从 GC 可达性看完整引用链把存储模型翻译成人话Thread对象持有一个ThreadLocalMapMap 的Entry通过弱引用指向ThreadLocal同时通过强引用指向 value。一个 value 要被安全回收必须满足没有任何一条从 GC Roots 出发的强引用链能到达它。普通场景下这条链是Thread (强) - ThreadLocalMap (强) - Entry (强) - value (强)。线程结束Thread不可达整条链断了value 自然被回收。所以很多人说“ThreadLocal 不会内存泄漏”这句话在“线程一定会结束”的前提下是成立的。但线程池把前提改了。工作线程是长期存活的核心线程Thread对象作为 GC Root 一直挂在那里。此时 value 能不能被回收完全取决于 Map 里有没有人清它。人话就是你在普通线程里用完不清理顶多脏到自己线程结束你在线程池里用完不清理就等于把对象钉在了一个永远不销毁的容器上。3.2 value 是如何被“钉死”的形成泄漏通常需要同时满足两个条件ThreadLocal实例不再被业务代码持有或者虽然持有但业务已经结束value 在业务上已经无用当前线程存活且没有人调用过remove。如果 key 本身还被外部强引用比如static字段Entry 永远不会变成陈旧项value 就会一直活着——这是最常见的“进程内存只涨不降”。如果 key 已经没人引用了GC 之后 Entry 会变成 key 为 null 的陈旧项但 value 仍然被强引用拽着只能等下一次set、get或rehash触发清理时才有机会被回收。问题在于这个清理时机完全不可控在并发量低、操作不频繁的线程池里垃圾可能很久都清不掉。从业务上看value 早已是垃圾从 JVM 的角度看它还是强可达的活对象。这中间的错位就是内存泄漏的全部秘密。3.3 三种典型的泄漏形态我把实践里见过的泄漏归纳成三种形态方便你对号入座形态一静态或长生命周期 key 线程池 忘记 remove。比如一个静态的ThreadLocalUser每次请求 set 用户信息处理完不清理。线程池线程被复用最后一次 set 的用户对象连同它关联的权限列表、部门信息、请求体残留在堆里。线上表现为老年代占用缓慢增长堆 dump 后能看到大量同一个业务类的实例。形态二动态创建的 key 不 remove。在方法内部临时new一个ThreadLocalset 后不清理。key 只剩弱引用GC 后 Entry 变陈旧value 仍活着。频繁执行且线程池线程固定的情况下数组里会积累不少 key 为 null、value 为业务对象的陈旧 Entry。这类问题更隐蔽因为堆 dump 里看不到ThreadLocal的强引用指向。形态三value 本身是大对象或持有容器类对象。单个 value 是几十 MB 的byte[]、数据库连接或者 IO 流时即使只有一个线程没清也能造成可感知的内存压力。这种场景最容易出现在把ThreadLocal当缓存用的设计里。3.4 顺带澄清内存泄漏和内存溢出不是一回事ThreadLocal造成的通常不是瞬间的内存溢出而是渐进式的内存占用。如果业务代码里还有循环创建大对象的叠加操作才可能把堆彻底打爆。排查时“某个类的存活实例数持续增长”这个特征比“GC 报 OOM”更容易暴露这类问题我后面会讲具体的分析入口。4. 生产环境避坑指南线程池、异步链路与上下文封装里的实战雷区4.1 最坑的写法线程池任务里 set 了不清理线程池提交任务时任务执行线程是复用的。假如任务 A 在某线程上设置了用户上下文但没 remove任务 B 如果只get不set拿到的就是 A 的用户数据——轻则日志串了重则产生越权查询。这不是理论推演我同事就遇到过线上一个导出任务把上一个用户的租户信息带进了下一个查询业务代码拿到错误的租户 ID 去查库一点报错都没有数据却错了。正确写法是 try-finally 兜底pool.submit(() - { UserContext.set(user); try { doBusiness(); } finally { UserContext.clear(); } });finally里的清理必须做否则异常路径照样泄漏。我见过太多只写 try 不写 finally 的代码异常一抛上下文就留在线程里了。4.2 InheritableThreadLocal 解决不了线程池里的上下文传递InheritableThreadLocal是ThreadLocal的子类创建线程时会把父线程的inheritableThreadLocals拷贝给子线程。注意是“创建线程时”拷贝一次。线程池里的工作线程是提前创建好的后续你往线程池提交任务子线程看到的还是创建时刻的快照父线程后来更新的值它根本看不到。所以只要涉及线程池InheritableThreadLocal基本不解决问题。业界通用方案是阿里开源的TransmittableThreadLocalTTL核心思路是“任务提交时快照、任务执行前恢复、执行后还原”。这里不展开 TTL 的实现细节但选型时建议直接用它替代手写上下文切换别自己造轮子。4.3 框架封装线程池后你的 remove 可能没执行很多框架会包一层任务执行器比如 Spring 的Async。一旦你配置了自定义线程池就得确认框架是否会帮你清理上下文——多数框架不会。RPC 框架的线程池通常自己管理ThreadLocal的生命周期但那是框架内部约定不代表你往线程池里塞的业务任务也能享受这个待遇。另一个容易被忽视的是异步回调场景你在主线程set的上下文在子线程的回调里get到 null 或者旧值。这不是ThreadLocal的 bug而是线程隔离的天然结果。要么显式把上下文作为参数传过去要么用 TTL 做线程间的快照传递。4.4 一套可落地的封装让 remove 变成强制而不是自觉我见过不少团队把ThreadLocal的使用约定写在 Wiki 里然后事故照出。比较靠谱的办法是把清理逻辑做成代码层面的约束。思路一是提供AutoCloseable包装把set和remove绑在一起public class UserContext implements AutoCloseable { private static final ThreadLocalUser HOLDER new ThreadLocal(); public static UserContext enter(User user) { HOLDER.set(user); return new UserContext(); } public static User get() { return HOLDER.get(); } Override public void close() { HOLDER.remove(); } }调用方想不清理都难因为 try-with-resources 会自动调用closetry (UserContext ignored UserContext.enter(user)) { // 业务逻辑 }思路二是做一个包装 Runnable在任务执行前保存当前线程的上下文快照执行后恢复原状既不会污染下一个任务也不会留下本次任务的数据public final class ContextRunnable implements Runnable { private final Runnable delegate; private final MapThreadLocal?, Object snapshot; private ContextRunnable(Runnable delegate) { this.delegate delegate; this.snapshot capture(); } public static Runnable wrap(Runnable task) { return new ContextRunnable(task); } Override public void run() { try { delegate.run(); } finally { restore(snapshot); } } }这只是一个骨架capture和restore需要根据项目里需要传播的ThreadLocal列表来实现。如果项目里已经用了 TTL直接用它的TtlRunnable就行不必重复造轮子。另外一个真实场景值得提Spring MVC 里用RequestContextHolder通常不出问题因为框架在 Filter 层做了兜底——请求前绑定请求后清理。这不是因为ThreadLocal安全而是因为框架替你补上了remove。4.5 静态字段、大对象与缓存误用还有一类坑是把ThreadLocal当缓存用。比如静态ThreadLocal里放一个 Map运营配置越堆越多线程还不退出。这已经不是ThreadLocal的问题而是内存设计的问题。真要缓存请用带过期策略的本地缓存框架别拿ThreadLocal当全局缓存使。5. 泄漏排查实录从最小 Demo 复现到堆转储定位再到修复验证5.1 复现一段能稳定复现 ThreadLocal 残留的 Demo先用最小 Demo 把问题复现出来方便验证后面的工具链。下面这段代码工作任务只做一件事往静态ThreadLocal里放一个 16MB 的数组然后假装处理业务。注意没有任何remove。public class ThreadLocalLeakDemo { private static final ThreadLocalbyte[] HOLDER new ThreadLocal(); public static void main(String[] args) throws Exception { ExecutorService pool Executors.newFixedThreadPool(4); for (int i 0; i 50; i) { pool.submit(() - { HOLDER.set(new byte[16 * 1024 * 1024]); try { Thread.sleep(100); } catch (InterruptedException ignored) { } // 模拟业务结束但忘记 HOLDER.remove() }); } pool.shutdown(); pool.awaitTermination(1, TimeUnit.MINUTES); System.out.println(所有任务已结束但堆里还留着每个线程最后一次设置的数组); Thread.sleep(Long.MAX_VALUE); // 让进程继续跑方便我们观察堆 } }用-Xmx128m跑这个 Demo任务执行到后半程大概率 OOM或者用jstat观察 Old 区不会下降。它模拟的就是生产环境里“请求处理完了对象还钉在长命线程上”的状态。5.2 抓堆快照jcmd 优先jmap 次之Arthas 兜底线上抓堆有两个原则一是尽量用不触发 Full GC 的方式抓二是别在生产高峰期随意执行。jcmd是 JDK 自带推荐优先使用jcmd pid GC.heap_dump /tmp/heap.hprofjmap也可以jmap -dump:formatb,file/tmp/heap.hprof pid注意jmap -dump:live会先触发一次 Full GC。泄漏对象是强可达的Full GC 清不掉所以 live dump 里仍然能看到它们但 live 参数会把那些本来可以回收的临时对象全部清掉快照会失真想还原现场时别用 live。如果你线上已经挂了 Arthas直接heapdump /tmp/heap.hprof就行不需要额外 attach 工具。像heapdump这类命令不会改动业务字节码风险可控但任何线上诊断命令都建议在低峰期操作。5.3 在 MAT 里定位 ThreadLocal 残留的两个入口把heap.hprof用 Eclipse MAT 打开有两个最快的入口。第一个是直查业务类的实例。菜单Open Query Browser - OQL执行SELECT * FROM com.example.BusinessContext查到大量实例后右键任意一个选择Merge Shortest Paths to GC Roots并且排除弱引用和软引用就会看到Thread - ThreadLocalMap - Entry - value这条经典路径。看到这条路径基本可以确定泄漏点在ThreadLocal上。第二个是直接查 Entry 数组SELECT * FROM java.lang.ThreadLocal$ThreadLocalMap$Entry重点看两类数据key 不为 null、value 不为 null 的 Entry说明ThreadLocal虽然被业务长期持有但值从未清理过key 为 null、value 不为 null 的 Entry说明ThreadLocal已经被 GC但 value 还挂在 Entry 上——这是“value 没被清理”的铁证。顺着 value 的运行时类名就能一路找到业务代码的set位置。5.4 修复与验证补上 remove然后证明堆稳住了修复本身不复杂把 Demo 里补上 finally 清理再跑一遍。用jstat观察jstat -gcutil pid 1000修复前 Old 区会持续爬升修复后任务跑完Old 区很快回收回到底线。稳妥起见可以加一个小的集成测试模拟线程池执行 N 个任务后断言工具类里的ThreadLocal当前值已经被清空。反射拿Thread.threadLocals检查在测试代码里是可行的Field field Thread.class.getDeclaredField(threadLocals); field.setAccessible(true); assertNull(field.get(Thread.currentThread()));注意这个断言只能测当前线程测不了线程池里其他工作线程。要测线程池线程得在任务内部把当前线程的threadLocals快照出来再在所有任务结束后统一检查或者直接断言任务里使用的上下文工具类在任务结束后取不到值。最后补一句经验之谈网上很多文章说“ThreadLocal 泄漏线程池关了就好”。线程池能关吗核心线程在应用生命周期内基本不退出所以你永远不能指望线程销毁来兜底清理动作必须发生在任务执行路径上。我个人在带团队时立了个规矩凡是把ThreadLocal引入业务代码必须同时给出三个东西——一个封装好的工具类、一段说明适用场景的注释、一个验证清理时机的测试用例。三者缺一Review 就过不了。这个规矩看起来死板但它确实让我们后面再没有因为ThreadLocal出过线上问题。