Java Remote Debug

该技能用于在源码目录中调试远程 Java 进程。

适用场景

• 连接启用了 JDWP 的远程 JVM
• 在业务类上设置断点、条件断点、方法断点
• 查看断点现场的局部变量、对象字段和调用栈
• 单步执行，或步出并查看返回值
• 在缺少 -g:vars 时，结合源码恢复方法参数名

前提条件

• 本机可用 node
• 远程 JVM 已开启 JDWP 调试端口
• 当前工作目录最好是对应项目的源码根目录

远程 JVM 启动参数示例：

-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005

使用方式

在技能目录执行：

node cli.js 

如果你是在项目源码目录中调用技能，建议显式指定工作区根目录：

JAVA_DEBUG_WORKSPACE_ROOT=$PWD node /path/to/java-remote-debug/cli.js 

说明：

• cli.js 会自动拉起本地调试服务
• 默认使用当前目录作为源码工作区
• 源码工作区用于参数名恢复和源码路径断点解析

常用命令

连接远程 JVM：

node cli.js connect 127.0.0.1:5005

查看状态：

node cli.js status

断开连接：

node cli.js disconnect

查看线程：

node cli.js threads

查看当前调用栈：

node cli.js stack

查看当前变量：

node cli.js vars

继续执行：

node cli.js continue

等待断点命中：

node cli.js wait 60000

查看当前断点现场：

node cli.js inspect

查看所有断点：

node cli.js breakpoints

查看对象字段（对象 ID 可从 vars 输出中获取）：

node cli.js fields 23379
node cli.js fields 23379 --maxDepth 2

列出已加载类：

node cli.js classes 'com.example.*'

断点用法

按类名和行号下断点：

node cli.js bp com.example.order.OrderController:81

按源码路径和行号下断点：

node cli.js bp src/main/java/com/example/order/OrderController.java:81

按方法名下断点：

node cli.js bp com.example.order.OrderController#queryList

按重载方法下断点：

node cli.js bp 'com.example.order.OrderController#queryList(java.lang.String,int)'

行断点加条件：

node cli.js bp com.example.order.OrderController:81 --if 'pageNo == 1'

方法断点加条件：

node cli.js bp 'com.example.order.OrderController#queryList(java.lang.String,int)' --if 'keyword != null'

清除断点：

node cli.js clear 12
node cli.js clear com.example.order.OrderController:81

单步调试

步过：

node cli.js step over

步进：

node cli.js step into

步出：

node cli.js step out

服务管理

通常不需要手工管理，本地服务会由 cli.js 自动启动。

如果需要手工启动或停止：

node cli.js server start --port 4711
node cli.js server stop

环境变量

• JAVA_DEBUG_WORKSPACE_ROOT：源码工作区根目录。默认是当前目录
• JAVA_DEBUG_SERVER_PORT：本地调试服务端口。默认 4711
• JAVA_DEBUG_SERVER_HOST：本地调试服务地址。默认 127.0.0.1

变量查看说明

vars 命令会优先显示真实局部变量。

如果目标类缺少 LocalVariableTable，会自动回退到 slot 推断模式。

如果当前工作区中能定位到对应源码，还会尝试恢复方法参数名，因此你看到的结果可能是：

• 真实局部变量名
• 源码恢复后的方法参数名
• 回退后的 arg0、arg1

当前能力边界：

• 对方法参数名恢复支持较好
• 不保证恢复方法体内部所有局部变量名
• 如果源码与远程运行版本不一致，恢复结果可能不准确

对象查看说明

vars 命令中的复杂对象显示为 ，可用 fields 命令查看其字段。

fields 命令会自动做一些友好化展示：

• 自动展开第一层对象字段
• 自动解析 String
• 自动拆箱包装类型（Integer → 数字）
• ArrayList 自动展开元素内容，空列表显示 []，有元素显示 [elem1, elem2] (size=N)
• HashSet/LinkedHashSet/TreeSet 同样自动展开元素
• HashMap/LinkedHashMap 自动展开为 {key1=value1, key2=value2} (size=N)

如果 List 中的元素是对象，会显示对象 ID，可继续用 fields 逐层钻取。

典型流程

1. connect 连接远程 JVM
2. bp 设置断点
3. wait 等待断点命中
4. inspect / vars / stack 查看现场
5. fields  查看对象字段和集合内容
6. fields  逐层钻取嵌套对象
7. step over / into / out 单步调试
8. continue 继续执行
9. disconnect 结束调试

注意事项

• 设置断点前，目标类需要已经加载
• 断点命中后线程会挂起，需要继续执行或单步
• 方法断点依赖行号信息；如果类缺少行号调试信息，可能无法定位第一条可执行语句
• 条件断点当前适合简单比较，如 ==、!=、null 判断
• 如果端口冲突，可调整 JAVA_DEBUG_SERVER_PORT 或 server start --port