1、简述
ThreadLocal 是 Java 中非常常用的工具类，常用于保存线程私有的数据，例如数据库连接、用户上下文、格式化器等。
但 ThreadLocal 若使用不当，会引发 隐性内存泄漏（Memory Leak），尤其在线程池环境中，更容易成为难以排查的生产事故源头。
本文将深入讲解 ThreadLocal 内存泄漏的原理、源码细节、最佳实践，并提供完整的可运行示例。
2、ThreadLocal 是如何保存数据的？
ThreadLocal 不是为每个 Thread 保存一个 Map，实际上是：
每个 Thread 都维护一个 ThreadLocalMap
ThreadLocal 作为 key，业务对象作为 value
示意结构：
Thread
└── ThreadLocalMap
├── Entry(ThreadLocal -> value)
├── Entry(ThreadLocal -> value)
└── Entry(ThreadLocal -> value)
关键点：
🔥 ThreadLocalMap 的 key 是 弱引用（WeakReference
🔥 value 是 强引用
这正是内存泄漏产生的入口。
3、为什么 ThreadLocal 会产生内存泄漏？
3.1 Key（ThreadLocal）是弱引用
源码：
static class Entry extends WeakReference<ThreadLocal<?>> {
Object value;
}
如果某个 ThreadLocal 对象没有外部强引用：
🔥 GC 会回收 key（即 ThreadLocal）
🔥 但是 value 不会被回收（因为 value 是强引用）
ThreadLocalMap 中会出现：
Entry(null -> value)
俗称 悬挂 Entry（Stale Entry）
3.2 value 无法被访问，但仍在占用内存
GC 只会清理 key，不会清理 value。
而 value 会一直存在，直到：
🔥 线程退出
🔥 或 map 触发 set/resize 清理机制
但是——如果使用线程池，这个线程不会退出！
因此 线程池 + ThreadLocal 忘记 remove = 100% 内存泄漏风险。
4、可视化示例：如何“泄漏”？
下面的示例会演示 ThreadLocal 的典型泄漏场景。
4.1 忘记 remove() 的 ThreadLocal
public class ThreadLocalLeakDemo {
private static final ExecutorService pool = Executors.newFixedThreadPool(1);
private static final ThreadLocal<byte[]> threadLocal = new ThreadLocal<>();
public static void main(String[] args) {
for (int i = 0; i < 1000; i++) {
pool.execute(() -> {
// 模拟占用大量内存
threadLocal.set(new byte[1024 * 1024]); // 1MB
// threadLocal.remove(); // 假如忘记 remove，会发生泄漏
});
System.out.println("第 " + i + " 次提交任务");
}
}
}
结果：
🔥 同一个线程反复保存 value（大对象）
🔥 因为线程来自线程池，不会退出
🔥 ThreadLocal 键被 GC 回收后，value 仍然强引用
🔥 value 永远不会被释放
🔥 最终导致 OOM（OutOfMemoryError）
4.2 ThreadLocalMap 的清理机制能避免泄漏吗？
答案：不能完全避免。
ThreadLocalMap 会在以下场景尝试清理：
🔥 set()
🔥 rehash()
🔥 resize()
源码片段（JDK8）：
if (e.get() == null) {
// 清理 key 被回收留下的 value
expungeStaleEntry(i);
}
但是：
🔥 如果你只 get() 不 set()
🔥 或线程长期不进行重哈希
🔥 或线程是线程池中的长期存活线程
那么 value 可能长期残留，形成内存泄漏。
5、如何避免 ThreadLocal 内存泄漏？
5.1 务必调用 remove()
try {
threadLocal.set(obj);
// do business
} finally {
threadLocal.remove();
}
永远放在 finally 块，保证执行。
5.2 不要用 ThreadLocal 保存大对象
例如：
🔥 大 List
🔥 大的序列化对象
🔥 大的 byte 数组
这些天生易泄漏。
5.3 在线程池中尤其要注意
线程池中的 Worker 线程生命周期极长。
ThreadLocal = 线程池中最容易出现的隐性泄漏点
5.3 建议使用 InheritableThreadLocal 要小心（更危险）
会在子线程中复制 value，更容易泄漏。
6、总结
ThreadLocal 内存泄漏是 Java Web 系统中最常见、最隐蔽、最难排查的性能问题之一。
ThreadLocal 泄漏的根本原因：
🔥 key 是弱引用 —— 容易被 GC 清除
🔥 value 是强引用 —— 容易残留
🔥 ThreadLocalMap 属于 Thread —— 线程池长时间不退出
🔥 因此 value 会长期停留在内存中 = 泄漏
解决方式：
🔥 永远在 finally 中 remove()
🔥 不在线程池中保存大对象
🔥 勤做内存快照排查 Stale Entry
