threadlocal 内存泄漏的核心是 key 为 null 而 value 强引用大对象，长期滞留于线程池等长生命周期线程的 threadlocalmap 中；需通过内存走势、gc 日志、mat 分析及代码审查定位并修复。
排查 ThreadLocal 未清理导致的内存泄漏，核心是确认“Entry 的 key 为 null、value 却强引用着大对象”，且该 Entry 长期滞留在复用线程的 ThreadLocalMap 中。这不是偶发问题，而是在线程池、Web 容器等长生命周期线程场景下必然积累的隐患。
看内存走势，快速判断是否可疑
先验证是不是泄漏，而不是一上来就分析 dump：
- 监控 JVM 堆内存（尤其老年代）：使用率随时间或请求量持续缓慢上升，Full GC 后无法回落到基线水平
- 观察 GC 日志：频繁出现
GC overhead limit exceeded，单次 Full GC 耗时明显增长（如 >1s） - 检查线程状态：线程池活跃线程数稳定，但服务运行数天后堆中
ThreadLocalMap$Entry实例数激增（MAT 中 Dominator Tree 可见） - 留意容器告警：Tomcat 日志出现
SEVERE: The web application appears to have started a thread...，提示上下文未清理
用 MAT 分析堆转储，定位脏 Entry
抓取堆快照后，重点不是找 ThreadLocal 对象，而是找它遗留的“尸体”：
Java Development Manual
下载
Java开发手册规约集合，基于阿里巴巴Java开发手册（嵩山版）。 涵盖7大维度：编程规约、异常日志、单元测试、安全规约、MySQL数据库、工程结构、设计规约。 当用户需要：(1) 编写或审查Java代码 (2) 检查命名/代码规范 (3) 处理异常和日志 (4) 编写单元测试 (5) 安全编码 (6) 数据库设...
- 用
jmap -dump:format=b,file=heap.hprof <pid></pid>获取 dump（建议在一次 Full GC 后执行，减少噪声） - 用 Memory Analyzer Tool（MAT）打开，进入 Dominator Tree
- 搜索
java.lang.ThreadLocal$ThreadLocalMap$Entry，按 retained heap 排序 - 筛选出
key == null但valueretained heap 很大的 Entry（例如指向byte[]、UserContext、DTO等） - 对典型 Entry 右键 → Path to GC Roots → 勾选 exclude weak/soft references：若路径终点是某个
static final ThreadLocal字段或业务类中的 ThreadLocal 成员变量，就锁定了泄漏源头
查代码逻辑，聚焦高危写法
泄漏不会凭空发生，往往集中在几类易被忽略的编码模式：
-
Lambda 或匿名内部类中 set 但没 remove：例如
executor.submit(() -> { tl.set(x); doWork(); })—— 缺少 finally 清理 - 非 static 的 ThreadLocal 实例：每个对象都 new 一个 ThreadLocal，导致 key 弱引用失效后，ThreadLocal 自身也堆积
- 工具方法封装了 set，但没暴露 clear 接口：调用方不知道要清理，或误以为“方法结束就自动释放”
- Filter / Interceptor 中存用户信息，但未在 finally 或 afterCompletion 中 remove：Web 场景最常见漏点
-
线程池自定义任务包装缺失清理钩子：未重写
afterExecute()或未使用TTL（TransmittableThreadLocal）替代
加防护手段，避免反复踩坑
靠人工 review 容易遗漏，需工程化兜底：
- 所有 ThreadLocal 操作必须用
try-finally包裹：try { tl.set(v); ... } finally { tl.remove(); } - 声明一律
static final，禁用局部 new ThreadLocal - 在线程池层面统一拦截：继承
ThreadPoolExecutor，重写afterExecute()，自动遍历并清理当前线程的threadLocals - 关键模块接入
TransmittableThreadLocal（TTL），它自带清理机制且支持父子线程传递，比原生更健壮 - JVM 启动参数加上
-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/path/，确保 OOM 时自动留证
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
