ThreadLocal 内存泄漏本质是 value 被强引用滞留而 key 因弱引用被回收，形成 key 为 null 的“幽灵条目”；必须显式调用 remove() 彻底移除 Entry，尤其在线程复用场景中需 try-finally 保障执行。

ThreadLocal 的内存无法回收，本质是 value 被强引用钉在 ThreadLocalMap 里，而 key（ThreadLocal 实例）却因弱引用被 GC 回收了，留下键为 null、值仍占内存的“幽灵条目”。这不是 GC 失效，而是设计上留出的清理责任——必须由开发者主动切断 value 的强引用链。

明确 ThreadLocalMap 的引用结构

每个线程的 ThreadLocalMap 中，Entry 继承自 WeakReference：

• Key 是 ThreadLocal 实例的弱引用：只要外部无强引用，下一次 GC 就会清空 key（变成 null）
• Value 是你存进去的对象的强引用：只要 Entry 还在 map 里，value 就不会被回收
• Thread → ThreadLocalMap → Entry(key=null, value=强引用对象) → 内存泄漏

必须显式调用 remove() 断开 value 引用

remove() 是唯一能安全清除整个 Entry 的操作，它不只是把 value 设为 null，而是从 Entry 数组中真正移除该槽位，并触发后续清理逻辑。

Java Api Extractor

从 Java 项目中提取 Controller 层接口定义为 JSON 数据。

下载

• 不要只依赖 set(null)：这只会让 value 变成 null，Entry 本身还在，key 仍可能为 null，map 容量不释放
• 必须在业务逻辑结束时调用 threadLocal.remove()，尤其在线程复用场景（如线程池、Web 容器请求线程）
• 推荐写在 try-finally 块中，确保异常也不会跳过清理

避免让 value 成为大对象或上下文容器

value 越重，泄漏危害越大。轻量对象（如 Integer、String）泄漏影响有限；但以下类型极易引发 OOM：

• 大字节数组（byte[1024*1024*10]）、缓存 Map、JSON 树结构
• Spring 上下文、DAO 实例、数据库连接、未关闭的 InputStream
• Activity 或 Fragment 引用（Android 场景），会导致整个 UI 层无法回收

配合使用 WeakReference 包装敏感 value（进阶）

若业务确实需要长期在线程中持有某对象，又担心泄漏，可自行用 WeakReference 包一层：

• 存入：threadLocal.set(new WeakReference(expensiveObj))
• 取出：WeakReference ref = threadLocal.get(); T obj = ref != null ? ref.get() : null;
• 这样即使忘记 remove，value 也能随 GC 自动释放，代价是需容忍 get() 返回 null

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南