ThreadLocal未清理是JVM内存泄漏高频原因，尤其在线程池复用场景下会快速累积OOM；典型特征为ThreadLocalMap中key为null但value强引用大对象的“幽灵Entry”，需通过jmap、MAT、jstack等工具定位长期存活线程及未remove代码点，并在try-finally中强制remove预防。
ThreadLocal 未清理是 JVM 内存泄漏的高频原因，尤其在线程池复用场景下，泄漏会快速累积并最终触发 OOM。定位关键不在于等崩溃，而是在堆内存结构中主动识别“可回收却未回收”的残留痕迹。
盯住 ThreadLocalMap 中的“幽灵 Entry”
ThreadLocal 泄漏最典型的堆内特征是：大量 ThreadLocalMap$Entry 对象存在，其 key == null，但 value 指向大对象（如 byte[]、UserContext、TraceContext 等）。这些 Entry 已无法通过 ThreadLocal 访问，却因强引用阻断 GC，俗称“幽灵条目”。
- 用
jmap -histo:live <pid>查看是否异常多的java.lang.ThreadLocal$ThreadLocalMap$Entry或你自定义的 value 类型（如com.example.Context） - 用
jmap -dump:format=b,file=heap.hprof <pid>抓堆快照，用 MAT 打开后执行 Leak Suspects Report，重点关注 “ThreadLocalMap → Entry → value” 链路 - 在 MAT 的 Dominator Tree 中筛选
java.lang.Thread，展开每个线程的threadLocals字段，检查其table数组里是否存在大量 key 为 null 的项
锁定长期存活且被复用的线程
短期线程泄漏影响有限；真正危险的是 Tomcat 的 http-nio-8080-exec-*、Spring Boot 默认的 ForkJoinPool.commonPool 或自定义线程池的核心线程——它们可能已运行数小时甚至数天，持续累积未清理的 value。
deep-java-review
下载
Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...
- 用
jstack <pid>观察线程名与状态，确认哪些线程长时间存活且处于RUNNABLE或WAITING - 结合应用日志或 Micrometer + Prometheus 监控，看某线程是否连续处理了数百/数千个请求却未重启
- 重点审查这些线程执行过的路径：Filter、Interceptor、AOP 切面、
Runnable/Callable提交点——这些位置常 set 了 ThreadLocal，但 return 前没 remove
验证是否真因未 remove 导致堆积
不靠猜测，用轻量级手段实时验证：
立即学习“Java免费学习笔记（深入）”；
- 在疑似泄漏点加诊断日志：
if (threadLocal.get() != null) { log.warn("ThreadLocal value still present before set: {}", threadLocal.get().getClass().getSimpleName()); }
若日志高频打印，说明前一次任务结束时未清理，当前 set 实际已造成旧值泄漏 - 在线程池场景下，临时重写
ThreadPoolExecutor.afterExecute()，统一检查threadLocal.get() != null并打印线程名和堆栈，快速定位漏删位置 - 对 Lambda 表达式中使用 ThreadLocal 的情况，用 MAT 搜索
$$Lambda$或lambda$字样，再看其 GC Roots 是否指向长期存活线程，基本可锁定泄漏源头
从代码层建立防御习惯
排查是事后手段，预防才是根本：
- 所有
threadLocal.set()必须包裹try-finally，确保异常路径也能执行remove() - 避免静态 ThreadLocal 存储业务对象；如必须用，配套提供
reset()或clearAll()工具方法 - 在 Filter/Interceptor 的
finally块中统一调用清理逻辑，而非依赖每个业务方法自行处理 - 用 IDE 全局搜索
.set(和->相邻的行，人工核对是否每处都有对应.remove()或封装
