如何在IntelliJ Ultimate中调试Gradle构建的远程Spring Boot应用

报错根因 #

你当前遇到的握手失败报错核心原因是混淆了应用业务端口和JVM调试端口：8082是Spring Boot处理HTTP请求的业务端口，远程调试需要使用独立的JVM调试端口，二者不能共用，因此直接连接8082会被拒绝。
另外你当前直接用./gradlew bootRun启动应用时，默认没有开启JVM调试端口，也是连接失败的原因之一。

完整配置步骤 #

步骤1：开启Gradle bootRun的调试模式 #

有两种配置方式，按需选择即可：

临时开启（单次启动生效）

直接在启动命令中添加调试参数：

# 默认开启5005作为调试端口
./gradlew bootRun --debug-jvm
# 如需自定义调试端口，使用如下命令，端口可自行修改，注意不要和已有端口（包括8082）冲突
./gradlew bootRun --jvm-debug=0.0.0.0:5005

永久配置（每次bootRun自动开启调试端口）

在项目的build.gradle中添加bootRun任务的JVM参数配置：

tasks.named('bootRun') {
    // 5005为调试端口，可自行修改，suspend=n表示应用无需等待调试器连接即可启动
    jvmArgs '-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005'
}

配置完成后直接执行./gradlew bootRun即可自动开启调试端口。
启动成功后控制台会输出如下日志，代表调试端口已正常监听：

Listening for transport dt_socket at address: 5005

步骤2：配置IntelliJ远程调试 #

• 打开IntelliJ右上角运行配置下拉菜单，选择「编辑配置」
• 点击左上角+号，选择「远程JVM调试」新建配置
• 按如下参数填写：
  • 名称：可自定义，例如SpringBoot远程调试
  • 主机：本地调试填localhost，远程服务器调试填服务器IP
  • 端口：填步骤1中配置的调试端口（例如5005，不要填应用的8082端口）
  • 使用模块的类路径：选择你当前的Spring Boot项目模块
• 点击「确定」保存配置。

步骤3：启动调试 #

• 先确保Spring Boot应用已通过bootRun命令启动完成，调试端口正常监听
• 选择刚才新建的远程调试配置，点击调试按钮（虫子图标）启动
• 当IntelliJ控制台输出「Connected to the target VM, address: 'localhost:5005', transport: 'socket'」即代表连接成功
• 在需要排查的代码行打上断点，从UI发起对应请求即可命中断点进行调试。

常见踩坑说明 #

• 如果应用部署在远程服务器，需要确保调试端口的防火墙已开放，且步骤1中address参数配置为*:端口而非127.0.0.1:端口，否则仅允许本地连接
• 如需要调试应用启动阶段的逻辑，可以将suspend=n改为suspend=y，此时应用启动会暂停，等待调试器连接后才会继续执行

内容的提问来源于stack exchange，提问作者Vinay Vishwkarma