Java远程调试本质是JVM以-agentlib:jdwp参数启动并暴露JDWP端口，IDE作为客户端连接；失败主因是JVM未开启调试、网络拦截或源码与字节码不匹配。
Java远程调试本质是JVM启动时开启调试端口
远程调试不是IDE单方面“连上服务器”，而是目标JVM必须以调试模式启动，并暴露一个可被外部访问的JDWP（Java Debug Wire Protocol）端口。IDE只是客户端，没有服务端（即带-agentlib:jdwp参数的JVM）就什么都连不上。
常见错误现象：Connection refused、Unable to connect to target VM、IDE显示“Waiting for connection”但一直转圈——八成是JVM根本没开调试，或者防火墙/网络策略拦了端口。
- 必须在启动Java进程时加JVM参数：
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -
suspend=n表示不阻塞启动；若设为y，JVM会卡住等调试器连接，适合排查启动阶段问题 -
address=*:5005在JDK 8及更早版本写成5005即可；JDK 9+要求显式写*:5005才能监听所有网卡，否则只绑localhost - 生产环境慎用
address=*，应限制绑定IP或配合防火墙白名单
IntelliJ IDEA连不上远程JVM的典型原因
IDEA的“Remote JVM Debug”配置本身很简单，但失败往往出在环境细节上。它不校验目标是否真在运行，只管发连接请求，所以报错后得倒查JVM侧。
使用场景：本地IDE调试部署在测试机、Docker容器或K8s Pod里的Spring Boot应用。
立即学习“Java免费学习笔记（深入）”；
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
- 确认JVM进程确实在跑：
ps aux | grep jdwp或jps -lvm看启动参数里有没有-agentlib:jdwp - 检查端口是否真被监听：
netstat -tuln | grep :5005（Linux）或lsof -i :5005（macOS） - Docker容器要加
-p 5005:5005且JVM参数中address不能写localhost（容器内localhost ≠ 宿主机） - K8s需确保Service或Port Forward打通，且Pod内JVM绑定的是
0.0.0.0而非127.0.0.1
VS Code用CodeLLDB或Java Extension调试远程JVM的区别
VS Code本身不原生支持JDWP，得靠扩展。主流两种路径：一是用Extension Pack for Java（含Debugger for Java），走标准JDWP；二是误用CodeLLDB（那是给C/C++/Rust的），完全不兼容Java字节码。
性能影响：JDWP协议本身有开销，尤其开启“方法进入/退出断点”或高频变量求值时，可能让远程服务响应变慢，非必要别在生产环境开着。
- 务必装
Debugger for Java（由Microsoft提供），不是CodeLLDB - 配置
launch.json时，type必须是java，request填attach，hostName和port对应远程地址与端口 - 如果用
Remote-SSH扩展直连服务器再本地启动JVM，那属于“本地调试”，不算远程调试，无需JDWP参数 - JDK版本要匹配：IDE用JDK 17调试，远程JVM最好也用JDK 17，跨大版本（如IDEA用JDK 21连JDK 8）可能因JDWP协议差异失败
远程调试时断点不生效的隐藏条件
断点灰色、提示“no executable code found”或“will not be hit”，不是IDE毛病，是源码、字节码、类路径三者对不上。Java调试依赖准确的源码映射，而远程环境下这三样最容易脱节。
容易踩的坑：用IDEA编译的class、却把Maven打包的jar扔到服务器上运行；或服务器用JDK 11编译，本地用JDK 17打开源码。
- 确保远程JVM加载的class文件，和你IDE里打开的源码是同一份构建产物（推荐用
mvn compile后把target/classes整个同步过去，而非只传jar） - 检查IDE里Module的
Sourcepath是否指向正确目录，且没被其他同名包覆盖 - Spring Boot Fat Jar调试困难，建议改用
spring-boot-devtools热部署，或直接解压jar、用-cp方式启动以便定位class路径 - 混淆过的代码（如ProGuard）无法调试，远程环境禁用混淆，或保留
mapping.txt并在IDE里手动关联
远程调试真正麻烦的从来不是“怎么连”，而是连上了之后，发现断点不进、变量看不到、堆栈对不上——这些都得回到类加载和构建一致性上去找。
