VSCode 调试多模块 Maven Spring Boot 后端踩坑：3 个配置缺一不可

有没有遇到过这种糟心时刻：后端 Spring Boot 项目在本地用 mvn spring-boot:run 跑得顺顺当当，一进 VSCode 点调试按钮，不是报「找不到主类」，就是配置文件不生效、连不上本地数据库？尤其是多模块的 Maven 项目，这种问题出现的概率能到 90%。
最近我在调某工业数据中台的多模块 Maven 项目时就踩了这个坑，折腾了半天才发现，VSCode 的 Java 调试默认根本不认多模块结构，缺了 3 个核心配置怎么都跑不起来。今天就把踩坑过程和解决方案整理出来，帮你少走弯路。

一、为什么多模块 Maven 项目在 VSCode 里直接跑会报错？

VSCode 的 Java 扩展不像 IDEA 那样会自动识别 Maven 多模块的父子依赖关系，默认的调试配置只会读根目录的结构，根本找不到子模块的编译产物和配置文件。我们当时遇到的两个最典型的报错就是：

1. 报 Error: Could not find or load main class：因为调试器默认找的是根目录的编译输出，根本找不到子模块的主类；
2. 配置文件完全不生效：启动时读的是根目录的配置，连数据库地址都是错的，更别说本地需要的 dev 配置了。

二、launch.json 必须补全的 3 个核心配置

针对多模块项目的调试需求，我们需要手动补全 launch.json 的三个核心字段，配置范例如下（敏感路径已泛化，使用时替换为实际项目路径即可）：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "java",
      "name": "Launch 业务子模块 (本地调试)",
      "request": "launch",
      "mainClass": "com.example.manage.ManageApplication", // 替换为你的子模块主类全限定名
      "projectName": "对应子模块的Maven工程名",
      "workingDirectory": "${workspaceFolder}/子模块目录名", // 核心1：指向要运行的子模块根目录
      "modulePaths": [ // 核心2：指向子模块编译后的产物路径
        "${workspaceFolder}/子模块目录名/target/classes",
        "${workspaceFolder}/子模块目录名/target/test-classes"
      ],
      "args": "--spring.profiles.active=local" // 核心3：指定本地调试环境
    }
  ]
}

三个字段的作用分别是：

• workingDirectory 是最容易被忽略的：如果不指定，VSCode 默认用工作区根目录作为启动目录，Spring Boot 会去读根目录的配置文件，根本找不到子模块的 application.yml，我之前就是没配这个，启动后连的居然是测试库，差点把测试数据搞乱。
• modulePaths 是解决「找不到主类」的核心：多模块项目的编译产物都在各自子模块的 target 目录下，必须显式告诉调试器去哪找编译后的 class 文件。
• args 里的环境参数是保命符：一定要指定本地 profile，不然默认可能会连生产或者测试环境，轻则配置不生效，重则污染线上数据。

三、除了改配置，还要做对 2 个前置操作

很多时候配置写对了还是跑不起来，是因为忽略了项目打开方式和编译状态两个前置条件：

1. 不要直接把整个多模块项目的根目录拖进 VSCode：正确的打开方式是要么直接打开你要调试的那个子模块的文件夹，要么用工作区配置（.code-workspace 文件）把对应的子模块单独加进来，不然 VSCode 的 Java 扩展根本识别不了子模块的 Maven 结构，配置怎么写都白搭。
2. 配置调不通先跑全量编译再调试：如果 launch.json 怎么改都报错，先在 VSCode 终端切到子模块目录，跑一遍 mvn clean install -DskipTests 把全量依赖和子模块都编译完，再点调试，成功率能高 80%。要是还是有问题，直接把调试面板的完整报错贴出来，比瞎试配置高效得多。

写在最后

多模块项目在 VSCode 里调试确实比 IDEA 麻烦，但核心逻辑其实很简单：就是要把 VSCode 的默认配置从「根目录」改成「你要运行的子模块」的路径。给大家总结 3 个可带走的方法：

1. 优先直接打开子模块目录，不要用根目录作为工作区；
2. launch.json 里必须补全 workingDirectory、modulePaths、环境参数三个字段；
3. 调试前先跑一次子模块的全量编译，避免缺 class 文件。

最后提醒大家：调试前一定要确认 profile 是不是本地，不然连错库、改错数据哭都来不及。