---
name: java-remote-debug
description: 通过 CLI 连接远程 JVM 进行 Java 调试，支持断点、条件断点、方法断点、单步、变量查看、调用栈和返回值检查。适用于需要在源码目录中调试远程 Java 进程、查看运行时状态或定位业务链路问题的场景。
---

# Java Remote Debug

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

## 适用场景

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

## 前提条件

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

远程 JVM 启动参数示例：

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

## 使用方式

在技能目录执行：

```bash
node cli.js <command>
```

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

```bash
JAVA_DEBUG_WORKSPACE_ROOT=$PWD node /path/to/java-remote-debug/cli.js <command>
```

说明：

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

## 常用命令

连接远程 JVM：

```bash
node cli.js connect 127.0.0.1:5005
```

查看状态：

```bash
node cli.js status
```

断开连接：

```bash
node cli.js disconnect
```

查看线程：

```bash
node cli.js threads
```

查看当前调用栈：

```bash
node cli.js stack
```

查看当前变量：

```bash
node cli.js vars
```

继续执行：

```bash
node cli.js continue
```

等待断点命中：

```bash
node cli.js wait 60000
```

查看当前断点现场：

```bash
node cli.js inspect
```

查看所有断点：

```bash
node cli.js breakpoints
```

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

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

列出已加载类：

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

## 断点用法

按类名和行号下断点：

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

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

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

按方法名下断点：

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

按重载方法下断点：

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

行断点加条件：

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

方法断点加条件：

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

清除断点：

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

## 单步调试

步过：

```bash
node cli.js step over
```

步进：

```bash
node cli.js step into
```

步出：

```bash
node cli.js step out
```

## 服务管理

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

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

```bash
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` 命令中的复杂对象显示为 `<object:ID>`，可用 `fields` 命令查看其字段。

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

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

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

## 典型流程

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

## 注意事项

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