VSCode调试多模块Maven项目失败，主因是缺三个关键配置：语言服务自动同步Maven构建、launch.json补齐类路径、调试前强制编译最新代码。
VSCode 本身不自动识别“哪个项目该用哪个调试入口”，它只按 launch.json 里写的路径和参数启动进程。多项目场景下，入口错一个字符、路径少一级、模块没编译，就直接报 NoClassDefFoundError 或 Could not find or load main class。
每个项目必须有独立的 .vscode/launch.json
VSCode 的调试配置不是全局的，也不是按工作区统一生效的——它默认只读取当前打开文件夹（或工作区中被选中的根文件夹）下的 .vscode/launch.json。如果你把 api-service 和 web-client 都加进同一个工作区，但只在 api-service 目录里放了 launch.json，那切换到 web-client 文件里按 F5，VSCode 就会 fallback 到默认行为（比如尝试运行当前打开的 JS 文件），大概率失败。
- 确保每个子项目根目录下都有自己的
.vscode文件夹，并且里面包含针对该项目的launch.json - 不要把所有配置堆在一个工作区级的
launch.json里——VSCode 不支持跨根目录的配置继承 - 如果用多根工作区（
.code-workspace），各项目的launch.json仍各自独立加载，互不影响
program 和 cwd 必须指向实际可执行产物
Java/Spring Boot 项目常见错误是把 program 写成 ${workspaceFolder}/src/main/java/com/example/App.java ——这根本不是 JVM 能加载的东西。JVM 启动的是 class 或 jar，不是源码。
- Spring Boot 项目：通常设为
"program": "${workspaceFolder}/target/myapp-0.1.0.jar"，前提是已执行过mvn package - 普通 Java 主类：需确保对应模块已编译，路径形如
"program": "${workspaceFolder}/target/classes"，再配合"mainClass": "com.example.Application" -
cwd（working directory）要设成该模块的根目录，否则相对路径的配置文件（如application.yml）会找不到
多模块 Maven 项目必须显式指定主类与类路径
VSCode 不会像 IDEA 那样自动解析父 POM 和模块依赖关系。你得在 launch.json 里明确告诉它：“主类在哪”“哪些模块的 classpath 要加进来”。
- 用
"mainClass": "com.example.gateway.GatewayApplication"明确声明，不能依赖扫描 - 如果主类依赖其他子模块（比如
common-utils），必须确保该模块已编译，且其target/classes在 classpath 中——可通过"classPaths": ["${workspaceFolder}/common-utils/target/classes"]手动追加 - 避免用
mvn spring-boot:run思维：VSCode 调试 ≠ 执行 Maven 插件，它是直接拉起 JVM 进程，classpath 完全由你配置决定
调试前务必确认模块已编译，且无 stale class 文件
这是最隐蔽也最常被忽略的一环。VSCode 不监听 src 变更并自动编译，也不会清理旧 class。改完代码不手动编译，调试时跑的还是上一次的字节码。
- Java 项目建议在
launch.json中配"preLaunchTask": "compile"，并在.vscode/tasks.json里定义对应任务，例如调用mvn compile或javac - 检查
target/classes下是否存在对应包路径和.class文件，缺失就说明编译没走通 - 遇到 “断点灰色” 或 “变量显示 unavailable”，第一反应不是调试器坏了，而是 class 文件没更新或路径对不上
