VS Code中正确搭建Maven多模块项目的配置方法

前置准备 #

• 安装VS Code官方Java扩展包：Extension Pack for Java、Maven for Java，安装完成后重启VS Code，卸载非官方的第三方Java/Maven相关扩展避免配置冲突。
• 确认本地Maven环境配置正常，VS Code的Maven设置里指向的本地Maven路径、settings.xml路径和本地终端使用的配置一致。

操作步骤 #

1. 创建父工程

   • 打开命令面板（快捷键Ctrl+Shift+P/Cmd+Shift+P），执行Maven: Create Maven Project，按需选择archetype：不需要初始示例代码选maven-archetype-simple，需要基础Java项目结构选maven-archetype-quickstart。
   • 按提示输入groupId、artifactId、版本号，选择父工程的本地存储路径完成生成。
   • 打开父工程根目录下的pom.xml做核心配置：
     • 将<packaging>节点值修改为pom，默认生成的配置为jar，父工程仅做依赖、模块统一管控，本身不输出业务代码包。
     • 在<properties>节点下配置全局参数：

     <properties>
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
       <maven.compiler.source>17</maven.compiler.source>
       <maven.compiler.target>17</maven.compiler.target>
       <spring-boot.version>3.2.0</spring-boot.version>
       <spring-cloud.version>2023.0.0</spring-cloud.version>
     </properties>
     

     • 配置<dependencyManagement>节点统一管控第三方依赖版本，该节点仅声明版本不实际引入依赖，子模块引入对应依赖时无需填写版本号即可自动继承。
     • 所有子模块通用的公共依赖（如lombok、spring-boot-starter-test）直接放在父工程的<dependencies>节点下，所有子模块会自动继承，无需重复声明。
     • 保留空的<modules>节点即可，后续创建子模块时会自动写入模块配置，无需手动提前添加。
   • 删除父工程默认生成的src目录，父工程不需要存放业务代码，残留的src目录会触发classpath相关报错。

2. 创建子模块

   • 不要手动新建子文件夹再独立创建Maven项目，直接在VS Code资源管理器中右键父工程的根pom.xml，选择Maven: Create Module，或在VS Code Maven面板找到对应父项目，右键选择Create Module。
   • 按需选择子模块的archetype，按提示输入子模块的artifactId（如auth），Maven会自动在父工程目录下生成子模块文件夹，自动修改父工程<modules>节点添加子模块声明，同时自动在子模块的pom.xml中生成正确的<parent>节点关联父工程坐标，无需手动修改关联配置。
   • 子模块生成后检查<packaging>节点值，普通业务模块设为jar，需要外部容器部署的模块设为war即可，子模块无需重复声明groupId、version，自动继承父工程配置。

3. 项目加载与校验

   • 所有模块创建完成后，打开命令面板执行Java: Clean Java Language Server Workspace，选择重启等待Java语言服务重新加载全量项目。
   • 不要手动右键src目录执行Add Folder to Java Source Path操作，Maven项目默认识别src/main/java、src/test/java为源码目录，手动修改源路径会触发不支持操作的报错，源码路径配置统一通过各模块的pom.xml完成。

常见报错修复 #

• 报错App.java is not on the classpath of project parent, only syntax errors are reported：父工程残留了默认生成的src目录和Java文件，删除父工程下的src目录即可。
• 父工程依赖未同步到子模块：检查公共依赖是否放在父pom的<dependencies>节点下，放在<dependencyManagement>节点的依赖仅做版本声明，不会自动引入；执行Maven面板的Reload All Maven Projects操作刷新依赖。
• 子模块未被识别为Java项目：检查父pom的<modules>节点中子模块路径配置是否正确，执行Java语言服务清理缓存重启操作即可。

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