Java jcmd 怎样导出虚拟线程线程栈

Java 服务采用虚拟线程后，想查看线程栈不需要改业务代码，可以使用与目标 JVM 匹配的 jcmd。核心命令是 Thread.dump_to_file：它会把平台线程和虚拟线程一起写入文本或 JSON 文件。

官方地址：https://docs.oracle.com/en/java/javase/26/core/virtual-threads.html

先用文本格式快速阅读，交给工具处理时再用 JSON。需要特别记住：这类转储不是暂停 JVM 得到的一致快照，也不是完整的堆 dump 或死锁检测报告。

• 人工排查：导出 -format=text，直接搜索线程名、状态和调用栈。
• 程序分析：导出 -format=json，保留结构化对象和虚拟线程信息。
• 结果解释：同时记录 PID、JDK 版本、采集时间和权限边界，不把一次快照扩大成全局结论。

先确认目标 JVM 和诊断权限

最容易出错的地方不是参数，而是 PID。开发机上可能同时有多个 Java 进程，当前 shell 的 java 版本也不一定就是服务进程的版本。先列出可发现的 JVM，再对目标 PID 读取版本和命令帮助。

# 先列出当前用户可发现的 Java 进程，人工确认目标 PID
jcmd -l

# 把 12345 改成真实目标 JVM 的 PID，确认运行时版本
PID=12345
jcmd "$PID" VM.version

# 读取目标 JVM 支持的诊断命令，避免把别的 JDK 语法直接套过来
jcmd "$PID" help Thread.dump_to_file

如果 jcmd -l 看不到目标进程，先检查运行用户、容器的 PID 命名空间和 attach 权限。不要把“当前用户看不到”直接解释成“服务没有虚拟线程”。诊断命令还需要一个目标 JVM 可写的输出路径；容器内路径与宿主机路径可能不是同一个位置。

用 Thread.dump_to_file 导出文本线程栈

文本格式适合值班排查和人工搜索。命令中的路径应位于目标 JVM 所在环境，文件名中的 %p 可以让 JDK 用目标进程 PID 展开文件名，避免多进程同时诊断时互相覆盖。

# 使用目标 JVM 的 PID，把文本线程转储写到目标环境的诊断目录
PID=12345
jcmd "$PID" Thread.dump_to_file -format=text /var/tmp/vthreads-%p.txt

# 如果文件已存在，再显式允许覆盖；否则保留原文件以免误删上一份材料
jcmd "$PID" Thread.dump_to_file -overwrite -format=text /var/tmp/vthreads-%p.txt

得到文件后，可以先搜索虚拟线程名称、业务入口和状态，再结合采集时间判断它是否与问题窗口重合。官方说明这个命令会列出所有线程，包括虚拟线程，并带有线程栈、时间戳和锁信息；它的影响取决于线程数量，所以不适合在高频循环里反复导出。

这里的“包含虚拟线程”不等于“保留了所有运行时信息”。该转储不提供对象地址、JNI 统计和堆统计等传统诊断材料，也不会替代专门的内存分析。

需要工具解析时改用 JSON 格式

JSON 更适合交给脚本、故障平台或内部工具处理。它的价值是保留结构化字段，而不是让采集动作变成更强的运行时快照。

# 使用 JSON 格式输出，文件名仍带 PID 便于多进程材料归档
PID=12345
jcmd "$PID" Thread.dump_to_file -format=json /var/tmp/vthreads-%p.json

# 只有确认旧文件可以替换时才加 -overwrite，避免覆盖未归档的诊断材料
jcmd "$PID" Thread.dump_to_file -overwrite -format=json /var/tmp/vthreads-%p.json

文本与 JSON 的线程覆盖范围相同，差别主要在呈现方式。人工阅读时文本更直接；需要按线程状态、名称或容器关系筛选时，JSON 更容易被程序解析。无论选哪种格式，都应把文件路径、采集时间、目标 PID 和 JDK 版本写入诊断记录，而不是只上传一个没有上下文的文件。

按输出边界解释线程转储

Oracle 对虚拟线程的说明特别强调，Thread.dump_to_file 不会为了采集而暂停整个虚拟机，因此它不是 stop-the-world 意义上的一致快照。线程可能在采集过程中继续变化，文件中的时间戳正是解释材料的一部分。

它还包含锁相关信息，但不执行死锁检测。看到某个线程处于等待状态，只能说明采集时观察到了该状态，不能单凭这一行断言存在死锁；要确认死锁，应使用合适的锁诊断手段和重复观察窗口。

整理文件并安全结束诊断

一次可交接的诊断材料至少要有四项：目标 PID、JDK 版本、采集时间和输出格式。再补充触发问题的请求时间、容器或主机边界，以及文件是否包含业务参数。线程栈可能暴露类名、路径、请求标识甚至参数片段，上传前应按团队的敏感信息规则处理。

如果问题是瞬时卡顿，可以在同一问题窗口内分别保存两份带时间的转储；如果要分析持续事件，则应结合 JFR 等专门记录工具。不要通过连续高频执行 jcmd 把诊断动作本身变成额外负载，也不要在没有权限确认时反复尝试 attach。

最终的判断顺序可以保持简单：先确认连接的是谁，再确认文件是否生成，接着确认里面是否有虚拟线程，最后才结合时间、调用栈和其它观测材料解释原因。

相关问题

• 文本和 JSON 应该选哪个？ 人工快速查看选文本；需要脚本筛选、归档或接入工具时选 JSON。
• Thread.dump_to_file 能确认死锁吗？ 不能。它提供锁信息，但官方说明不执行死锁检测。
• 为什么文件里有虚拟线程却不能还原完整现场？ 因为该命令不是暂停 JVM 的一致快照，线程状态可能在采集期间变化。