排查ThreadLocal残留的关键是确认本该被回收的值为何仍挂在子线程中，本质是ThreadLocalMap中entry被长期持有；需结合jstack、Arthas、堆转储及日志定位未remove位置。
排查这类问题，关键不是找“泄漏对象”，而是确认“本该被回收的 threadlocal 值为何还挂在子线程里”。它不一定是真正的内存泄漏，但会表现为堆内存缓慢上涨、gc 效率下降、甚至线程复用后上下文污染——本质是栈帧（或更准确地说，是 threadlocalmap 中的 entry）被意外长期持有。
看线程局部变量是否残留
主线程执行完就 remove() 了，但子线程（尤其是线程池里的）仍能读到旧值，说明值被继承下来且未清理。这不是 bug，而是 InheritableThreadLocal 和 TransmittableThreadLocal 的设计行为。
- 用
jstack -l {pid} > dump.log抓快照，搜索ThreadLocalMap相关关键词，重点关注WAITING或RUNNABLE状态的线程中是否有大量非空value - 配合 Arthas 执行：
watch java.lang.Thread getThreadLocals 'params[0].threadLocals.table.{? #this != null && #this.value != null}.size()' -n 1 -x 3，直接统计每个线程ThreadLocalMap中存活的 entry 数量 - 若发现某些线程（如
pool-1-thread-2）entry 数持续 > 5，且 value 类型是你自定义的上下文类（如AuthContext、TraceContext），基本可判定残留
查上下文传递链是否断裂
很多框架（如 Netty 解码器、WebFlux Filter、自研 RPC 上下文）依赖 ThreadLocal 跨 handler 透传状态，但异常路径容易跳过 remove()。
- 检查所有使用
ThreadLocal.get()的地方，是否都配了finally { tl.remove(); }；尤其注意decode()、doFilter()、handleRequest()等入口方法 - 若用了
TransmittableThreadLocal，确认是否搭配了TtlRunnable或TtlCallable包装；裸调executor.submit(runnable)会导致父子传递失效，但不会残留——而用了包装却没清理，才真正危险 - 异步 Servlet 场景中，
AsyncContext.start(Runnable)启动的线程默认不继承父线程 TL，但若手动做了上下文复制（比如反射读取inheritableThreadLocals），又忘了在子线程结尾remove()，就会形成假性泄漏
验线程生命周期与复用逻辑
线程池线程复用是放大问题的温床：一个线程跑完 A 请求留下 Context，接着跑 B 请求时，B 就会误读 A 的上下文，同时 JVM 认为这个 Context 还被线程引用着，无法回收。
- 检查线程池是否用了
ForkJoinPool或自定义ThreadFactory；这两者默认不重置ThreadLocal，必须显式在afterThreadCreated或beforeExecute中清空 - 观察
Thread.getName()是否重复出现（如pool-1-thread-1长期存活），再结合堆直方图（jmap -histo {pid}）看你的上下文类实例数是否随请求线性增长 - 临时加日志：在线程执行前后打印
tl.get() != null，例如log.debug("Before: {}", CONTEXT.get() != null)，快速定位哪段逻辑漏了清理
用堆转储确认是否真泄漏
所谓“假性泄漏”，是指对象本身可回收，但因线程还活着 + TL 没清理，导致 GC Roots 仍能触达它。要区分真假，得看引用链。
- 用
jmap -dump:format=b,file=heap.hprof {pid}生成堆转储，用 Eclipse MAT 打开 - 执行 “Leak Suspects Report”，重点看
ThreadLocalMap→Entry[]→value的引用路径 - 如果 value 的 GC Root 是
java.lang.Thread @ 0x…，且该线程状态是WAITING或TIMED_WAITING（比如在LinkedBlockingQueue.take()），说明只是线程没结束，不是代码写错——这是线程池正常行为，只需确保下次执行前清理即可
