ThreadLocal 这东西凡是做 Java 后端的人多少都听说过。我在面试里被问到过不下五次开场往往是同一句话“ThreadLocal 有去了解过么”然后下一句就追了过来“聊下 ThreadLocal 内存泄漏问题” 更早的时候我在一个交易系统里用 ThreadLocal 保存当前请求的上下文结果线上老年代持续上涨定位到最后才发现问题既出在 ThreadLocal 的引用结构上也出在我没有及时清理的使用习惯上。这篇内容我会从最基础的设计讲起再到源码里 getMap、Entry 的引用关系最后用一个真实排查案例收尾把 ThreadLocal 为什么会出现内存泄漏、怎么避免、怎么排查一次说清楚。无论你是刚学 Java 的入门者还是已经写过一阵子代码、想在面试里把这个问题答得有点深度的开发者都值得往下看一看。1. 先搞懂 ThreadLocal一个“变量分身”的故事1.1 没有它时线程安全难题长什么样在讲 ThreadLocal 之前要先理解它解决的是哪一类问题。比如一个经典的场景多个线程共享同一个SimpleDateFormat实例做日期格式化这个类内部的可变状态没有做并发保护两个线程同时调用format()时很可能出现数组越界、格式错乱、甚至死循环。很多人第一反应是加锁但锁让所有线程串行执行在高并发下吞吐量很难看。另外一种做法是每次创建新的SimpleDateFormat但这又带来了对象频繁创建和 GC 的压力。ThreadLocal 给出的方案非常朴素既然共享状态容易出问题那就不共享。把每个线程要用的数据复制一份各自维护各自的谁也不用等谁。这就像一间办公室里只有一台打印机所有人都排队用它后来改成每人桌上放一台自己的打印机互相完全隔离。线程和变量副本的对应关系就是由 ThreadLocal 管理的。其实 ThreadLocal 并不神秘它没有把数据放在某个静态 Map 里而是把容器放在了每个Thread对象内部。所以每一个线程取到的值天然就是自己这个线程里放进去的值天然不会和其他线程冲突。理解了这个基本模型后面再看内存泄漏就清楚多了。1.2 有了它之后数据是怎么做到互不干扰的先看一个最基础的使用方式。定义一个ThreadLocalString在 A 线程里 set 一个值在 B 线程里 set 另一个值两者各自 get拿到的都是自己线程放进去的内容。这个现象背后其实是一个叫ThreadLocalMap的内部类在起作用每个Thread对象里都有两个成员变量普通情况下用threadLocals继承场景下可能还会用到inheritableThreadLocals它们都是ThreadLocalMap类型默认是 null。当某个线程第一次调用 ThreadLocal 的 set 或者 get 时才会真正初始化这个 map。可以简单理解成ThreadLocal本身是索引Thread 内部的那张表才是真正存放数据的房间。你去 set 的时候其实就是往当前线程的threadLocals里放一个 Entry你去 get 的时候就是从这个线程自己的threadLocals里取 Entry。这种设计带来的好处非常明显。比如在 Web 框架里你需要在一次请求的过滤器中设置一个请求 ID然后在后续的 Controller、Service 中随时读取。如果没有 ThreadLocal就得把请求 ID 作为参数一层层传代码会变得非常啰嗦。而有了它只要保证同一条线程处理同一个请求就能在任意代码位置拿到上下文数据。除了请求跟踪用户登录信息、事务上下文、分页参数这类“一个线程内全局可见”的数据也都是 ThreadLocal 的典型使用场景。2. ThreadLocal 内存泄漏根源在于 Entry 的那条引用链2.1 Entry 的真实结构key 弱value 强要聊内存泄漏必须先看ThreadLocalMap.Entry的源码因为所有问题都藏在这个“看似简单”的内部类里。static class ThreadLocalMap { static class Entry extends WeakReferenceThreadLocal? { Object value; Entry(ThreadLocal? k, Object v) { super(k); value v; } } private Entry[] table; // ... }注意这里的继承关系Entry继承了WeakReferenceThreadLocal?构造时调用super(k)所以 Entry 里那个“key”实际上是一个弱引用。而value只是一个普普通通的强引用字段。这个结构是整个内存泄漏话题的起点。弱引用的特点是只要某个对象只被弱引用引用着垃圾回收时就可以被回收。换句话说如果一个 ThreadLocal 实例外面没有任何强引用指向它那么它作为 Entry 的 key在下一次 GC 时就会变成 null。可 value 是强引用的它不会因为 key 变成 null 就被回收。这么一来就形成了一个非常不对称的局面key 可能已经被回收了value 却还稳稳地待在 ThreadLocalMap 里。用一个生活化的比喻每个线程的 ThreadLocalMap 是一排工位抽屉ThreadLocal 是贴在抽屉上的便利贴value 是抽屉里放的文件。便利贴是用很差的纸做的时间一长自己就掉了但掉了便利贴的抽屉里文件并没有被拿出来还是一直占着柜子空间。内存泄漏说的就是这些“便利贴掉了但文件还在”的抽屉。2.2 key 变成 null不等于 value 被释放先明确一个容易混淆的点很多文章说“ThreadLocal 用了弱引用所以会导致内存泄漏”这个说法其实不太准确。弱引用不但不是泄漏的原因反而是设计者有意为之的一个缓解手段。真正的问题是 value 的强引用链没有断。当某个 ThreadLocal 对象的外部强引用没了比如它是在方法里new出来的局部变量方法执行完这个对象就只有 Entry 里的弱引用了。此时 GC 会先把 ThreadLocal 回收Entry 里的 key 变成 null。但请看这条强引用链当前线程对象Thread是可达的Thread 里有threadLocals字段threadLocals里有Entry[]数组数组里这个 Entry 还持有 value 的强引用。所以从 GC Roots 出发value 一直是可达状态GC 永远不会回收它。你可能想问既然设计者知道 key 会变成 null为什么不顺便把 value 也清掉其实 Java 的 ThreadLocal 内部是有“清扫”逻辑的。比如你调用 get、set、remove 的时候会走到expungeStaleEntry这类方法把 key 为 null 的 Entry 从数组里抹掉。但是注意这个清理动作是“惰性”的必须有人去碰同一个 ThreadLocalMap 才会触发。如果某个线程 set 过一次之后再也没碰 ThreadLocal又没有手动 remove那条 value 的引用就会一直存在直到线程死亡。所以更准确的表述是ThreadLocal 的弱引用设计可以把“ThreadLocal 对象本身无法回收”这个更严重的问题挡掉一半但 value 的回收仍然依赖后续操作一旦线程存活时间很长value 就会被一直拖住最终表现为堆内存持续增长。2.3 线程池为何是泄漏重灾区如果把同样的代码跑在普通线程里情况要好得多。普通线程执行完任务线程终止Thread 对象连同内部的 ThreadLocalMap 一起变成垃圾value 也就跟着被回收了完全不存在泄漏问题。真正让人头疼的是线程池。线程池里的核心线程会一直存活也就是说这些线程的ThreadLocalMap会一直存在。如果代码里在每次任务执行中 new 了一个新的 ThreadLocal 作为 key那执行一次就往 map 里塞一个 Entry任务跑完ThreadLocal 局部变量没有任何外部强引用weak key 很快变成 null但 value 还留在 Entry 里。随着任务不断执行map 里的“僵尸 Entry”会越积越多。还有一种更常见的情况ThreadLocal 是 static final 的每次任务只是 old value 被 new value 覆盖。这种场景不会堆积多个 Entry因为 key 是同一个反复 set 只会覆盖同一个 Entry 的值。但问题依然存在如果 value 是很大的对象、集合一旦 set 后不再使用又不 remove这个线程作为线程池常驻线程就会一直强引用着这份大对象。等同于线程池里每个线程都偷偷绑了一个大包袱内存占用老是不下去。用一个表格总结一下不同组合场景ThreadLocal key 来源线程生命周期最典型表现普通线程局部 ThreadLocal每次 new很快结束基本没问题线程死后 map 随之回收线程池局部 ThreadLocal每次 new常驻Entry 不断堆积老年代持续上涨线程池static ThreadLocal复用同一个常驻Entry 不多但 value 长期被强引用线程池static ThreadLocal finally remove复用同一个常驻每次用完即清无泄漏很多人踩坑都是踩在后两行。不是说 static ThreadLocal 就安全而是它的症状不同前者像“地基里堆了很多箱子”后者是“一个大箱子永远不放下来”。不管是哪一种线程池环境里如果不做清理都会造成内存泄漏。3. 从 getMap 源码入手看清 ThreadLocal 的存取机制3.1 getMap(t) 返回的是线程的 threadLocals 成员ThreadLocal 的源码很多人看过但真正注意到getMap的人不多。它在整个存取链路上扮演着入口角色。先看 get 方法public T get() { Thread t Thread.currentThread(); ThreadLocalMap map getMap(t); if (map ! null) { ThreadLocalMap.Entry e map.getEntry(this); if (e ! null) { SuppressWarnings(unchecked) T result (T) e.value; return result; } } return setInitialValue(); }而getMap的实现极其简单就是把线程对象内部那个兜兜拿出来ThreadLocalMap getMap(Thread t) { return t.threadLocals; }这段代码看起来平淡无奇但它包含了一个关键信息ThreadLocal 本身不存储任何值它只是“按图索骥”的那个索引。真正的 map 挂在 Thread 对象上。所以同一个 ThreadLocal 对象被多个线程使用时每个线程都从自己身上掏出自己的 map再用同一个 key 去查。这就是为什么不同线程 set 同一个 ThreadLocal 不会互相覆盖。另外一个容易被忽略的点是ThreadLocalMap的 key 是 ThreadLocal 对象本身但它的 Entry 不是用泛型存的而是用Object value。ThreadLocal 在 get 的时候会做一次强转。这意味着如果代码里把一些没完全设计好的数据塞进 ThreadLocal取出来的转型风险是你自己控制的。这不是泄漏问题但值得顺手提醒一句。还有一个细节InheritableThreadLocal会重写getMap和childValue返回线程里的inheritableThreadLocals字段。这样在创建子线程时Thread 构造函数会把父线程的 inheritableThreadLocals 复制一份给子线程。这个功能在使用线程池时尤其要小心因为线程池的线程属于复用创建子线程的“父子关系”并不像你想象的那么直观。我见过有人想用 InheritableThreadLocal 把 TraceId 传给异步线程池的子任务结果由于线程复用拿到的是上一次任务的旧值。这算是另一个层面的 ThreadLocal 坑。3.2 get/set/remove 里的清理逻辑为什么救不了你正因为getMap只是拿 map真正的查询逻辑都在ThreadLocalMap内部。ThreadLocalMap 用的是开放地址法不是链地址法它把 Entry 放在一个 Entry[] 数组里发生哈希冲突时向后探测。在 get 和 set 过程中一旦遇到 key 为 null 的 Entry就说明这个坑位已经“烂了”——key 已被 GCvalue 还没清理。这时 ThreadLocalMap 会调用expungeStaleEntry之类的逻辑去清扫。比如 get 的时候先根据 ThreadLocal 的 hash 找到对应的 index再顺着往下找如果 Entry 不为 null 且 key 指向同一个 ThreadLocal就返回 value。如果 Entry 还在但 key 已经变成 null就会把这个脏 Entry 清掉然后重新探测后续元素。set 的时候也类似发现脏 Entry 会替换或者顺手清理。remove 则是把当前 key 对应的 Entry 删除并调用一次 expungeStaleEntry。看到这里你可能会觉得“那就算不 remove以后我再用一次 get/set也会自动清理吧”理论上是这样但这里有三个致命的现实条件第一你必须再次操作同一个线程的 ThreadLocalMap而且最好命中到那些脏 Entry 附近。如果一个线程执行完任务后一直空闲没有任何后续 ThreadLocal 操作map 就一直没人打扫。第二线程池的线程虽然复用但任务之间可能间隔很长间隔期内堆积的脏 Entry 不会被触发。第三GC 只会把 key 清成 null它不会主动调用 ThreadLocalMap 的清理方法。也就是说垃圾回收器不认识这个内部数组里的“空 key 逻辑”。所以结论很直接源码里的清理逻辑只是“设计者尽力了”不是“你可以不清理”的理由。真正可靠的做法永远只有一个自己在 finally 里调用 remove。3.3 正确姿势用完 remove以及两个干净做法最标准的写法是这样的ThreadLocalRequestContext ctxHolder new ThreadLocal(); try { ctxHolder.set(ctx); // 业务处理中间随时可以 ctxHolder.get() } finally { ctxHolder.remove(); }remove会删除当前线程 map 里这个 key 的 Entry并把 value 置掉整条强引用链就此断开。不要抱着“反正内存泄漏也不是立刻崩”的侥幸心理线上内存曲线的每一次异常爬坡背后往往都是这种侥幸。比 try/finally 更省心一点的做法是做一个装饰器包装任务。在线程池提交 Runnables 时自动在任务执行前后清理 ThreadLocal。比如定义一个ThreadLocalRunnable执行前由调用方上下文初始化执行后调用全部已注册 ThreadLocal 的 remove。这样业务代码里就不用每个方法都写 try/finally但前提是有明确的 ThreadLocal 在范围内。还有一个很现实的建议能不用 ThreadLocal 就不用。尤其是只在单次调用链路里传递的值直接通过方法参数传过去一点问题都没有。ThreadLocal 的优势是隐式共享、少写参数但它也把调用关系变得不透明任何人都可能在某处塞个值、在另一处读出来排查上下文流动时很难受。我的原则是跨层传递用参数线程级全局上下文才用 ThreadLocal并且必须配清理。4. 一次线上 ThreadLocal 泄漏的真实排查记录4.1 从老年代曲线异常开始有一次我负责的定时任务服务出现了老年代持续增长的现象。这个服务用了一个定长线程池每 3 分钟跑一批任务处理完一批后线程并不销毁。起初 GC 日志显示老年代每次任务后都会涨几百 MBFull GC 后能降下来一些但降不到原来的水位。连续跑了几个小时后老年代使用率稳定爬升Full GC 间隔越来越短任务耗时偶发变长。当时第一反应是查是不是有集合忘清空了或者是第三方 SDK 缓存了什么对象。看了任务代码发现一个不太起眼的细节每个任务方法里都创建了一个 ThreadLocal 来保存该批次任务的汇总状态任务结束既没有 remove也没有清理逻辑。因为线程池线程是同一个ThreadLocal 又是局部变量方法执行完key 的外部强引用就没了很快变成 null但保存的汇总对象还挂在每个常驻线程的 ThreadLocalMap 里。这种泄漏很隐蔽因为它在代码表面看起来没有任何报错线程数量也没有涨但堆内存在缓慢地、不可逆地变大。排查内存问题的时候老年代增长是最典型的第一现象。如果你的服务里也有类似曲线先不要急着怀疑数据库连接池先看一眼有没有长生命周期线程和 ThreadLocal 的搭配。4.2 用堆转储锁定 ThreadLocalMap Entry 里的 value要证明是 ThreadLocal 在作怪最好的工具是堆转储。第一步先用 jmap 拿一份堆快照jmap -dump:live,formatb,fileheap.bin pid然后打开 MAT 或者 JProfile我可以选择先看 Histogram输入ThreadLocal过滤找到java.lang.ThreadLocal$ThreadLocalMap$Entry这个类。正常情况下它的实例数如果一直在增加而且里面很多 key 是 null那已经八九不离十了。接着用 Dominator Tree 从 Entry 对象往下一层一层展开看一下每个 Entry 的 value 是什么类型、有多少内存。当时展开后看到的是大量同一类的业务汇总对象每个大概几 MB整条线程存的合计下来有三四百 MB。再顺着参考链往回找能看到持有这些 Entry 的线程名清一色是定时任务线程池里的那几条线程。这里多说一句内存泄漏不只在 JVM 里存在操作系统层面也有分页缓冲池和非分页缓冲池内存泄漏这样的概念之前我查 Windows 系统句柄耗尽时也接触过定位思路大同小异——先找到谁占着分配的内存不释放再看它的生命周期和引用方式。Java 的排查优势在于堆转储可以非常直观地把引用链拉出来所以一定不要跳过 dump 这个步骤。4.3 修复验证和事后反思修复本身不复杂所有 ThreadLocal 的 set 之后都补上 finally remove。同时把任务中那个 ThreadLocal 改成方法参数在内部传递因为它的作用范围本身只有一次任务根本不需要跨线程访问。上线后我延续观察了两周老年代使用率曲线变得非常稳定Full GC 频率降到了原来的三分之一左右。复盘时我最大的感受是ThreadLocal 本身并不背锅真正背锅的是“长生命周期线程 短生命周期 ThreadLocal key 忘记 remove”这个组合。很多面试题喜欢直接问“ThreadLocal 是不是会内存泄漏”我觉得更准确的问法是在什么使用模式下会出现泄漏这样答案就有区分度也更能看出一个人到底是背题还是真懂。事后我也养成了一个习惯每次看到线程池提交任务都会先检查任务内有没有 ThreadLocal如果有就必须能在代码里明确回答“谁来清理”。答不出来就重构成参数传递。5. 常见问题速查与避坑清单5.1 面试高频追问怎么答如果把 ThreadLocal 内存泄漏问题放到面试场景我建议按下面这个层次回答由浅入深先说出结论ThreadLocal 的 key 是弱引用value 是强引用当 ThreadLocal 没有外部强引用时key 会被回收成 null但 value 还留在 ThreadLocalMap 里如果所属线程长期存活value 就一直可达这就是内存泄漏。回答到这里已经能超过半数候选人。如果面试官追问“为什么 key 不设计成强引用”你可以补充如果 key 是强引用即使外部已经不再使用某个 ThreadLocal 实例ThreadLocalMap 里的 Entry 仍然强引用着它ThreadLocal 对象本身就没法回收等于 key 和 value 一起泄漏问题更严重。用弱引用是为了至少让 key 能回收再配合 get/set/remove 时的惰性清理来降低 value 泄漏的影响。如果面试官继续追问“为什么 value 不用弱引用”这也是个好问题。如果 value 也是弱引用那么一旦某个线程的 ThreadLocalMap 里没有强引用指向 valuevalue 会在 GC 时被回收但数据你还在用呢拿到了一个 null功能直接没法工作。所以 value 必须强引用换句话说开发者必须手动管理它的生命周期。这套回答下来基本上能把 ThreadLocal 内存泄漏讲成一个完整的故事。5.2 被误认为是内存泄漏的几种情况排查和面试里经常有几种情况看起来像内存泄漏实际上不是。第一种线程池里用静态 ThreadLocal 存大对象但不更新。其实只有一个 Entryvalue 一直存在是预期行为因为那是线程内部状态。如果这个状态确实需要长期保留那不叫泄漏如果只是临时数据忘了 remove才叫泄漏。第二种每次 set 会覆盖旧值但旧对象已经被抛弃。这种情况虽然不会堆积多个 Entry但如果 value 很大长时间不 remove仍然占着内存。所以别因为“Entry 数量不多”就放松警惕。第三种普通线程结束threadLocals 没有手动清。线程对象都不可达了ThreadLocalMap 会连同整个线程一起被回收不属于泄漏。这个点很容易被面试题误导很多人一听到 ThreadLocal 就条件反射说“会泄漏”其实必须限定在“线程存活”这个前提。我把常见判断整理成了一个小表格现象是否真正泄漏判断依据普通线程结束后 map 未清理否Thread 对象整体不可达随 GC 回收线程池任务用局部 ThreadLocal 不 remove是key 为 nullvalue 被常驻线程强引用static ThreadLocal set 后一直不 remove视情况如果数据长期不需要则是泄漏同一个 key 反复 set 但不 remove不累积 Entry但最后一个 value 可能被长期持有线程池子线程通过 InheritableThreadLocal 复制数据需单独清理子线程复用时会残留父线程值5.3 记忆口诀与日常自查清单如果要把这篇文章压缩成一句话我会说弱 key 强 value线程不死 value 不灭用完 remove 最稳妥。记不住原理的时候先记住这个口诀至少能在写代码时不踩最基础的坑。日常自查我建议落实成清单代码里凡是出现 ThreadLocal先问这个值是不是某种“线程内全局态”如果是再看有没有线程池参与有线程池基本可以判定必须手动 removeset 和 get 不在同一个方法里时也要在入口处 tryfinally 里 remove关注 ThreadLocal 里存的对象大小不要存过大的 Session、上下文、集合类对象排查内存问题时不要只看堆栈的调用树直接用 MAT 搜 Entry 类。我个人在实际操作中的体会是ThreadLocal 像一把锋利的刀用得好可以让跨线程传递代码非常简洁用不好就是慢性内存杀手。很多人觉得内存泄漏离自己很远直到线上老年代曲线开始爬坡。下次你在代码里准备写threadLocal.set()的时候先停顿一秒想想哪个地方会执行remove()。想不清楚就改成参数传递一点都不丢人。这个坑我踩过所以希望你少踩一次。