Maven 多模块项目中依赖模块编译失败的根本原因与解决方案_技术教程

本文详解 maven 多模块项目中“子模块能被 ide 识别但 `mvn clean install` 编译失败”的典型问题，核心在于**非 spring 项目错误引入 `spring-boot-maven-plugin` 导致依赖模块未生成有效 jar 包**，致使下游模块编译时找不到类。

在 Maven 多模块项目中，一个常见误区是：只要父 POM 正确声明了，且子模块在中正确引用了其他子模块（如 abis-migrations-conversion），IDE（如 IntelliJ）就能正常解析并补全类——但这仅说明IDE 的 Maven 导入或缓存机制暂时“看到”了源码，并不代表该模块实际构建出了可被 Maven 依赖解析的制品。

从您提供的构建日志和 POM 文件可见，关键线索在于：

runtime-migrations-conversion 模块明确依赖 abis-migrations-conversion:1.0-SNAPSHOT；
错误信息全是 package ... does not exist 和 cannot find symbol，指向 com.hcb.neurotec.migrations.conversion.* 下的类；
这表明：*Maven 编译器在 classpath 中根本未加载 abis-migrations-conversion 模块的编译产物（即 target/classes/ 或 `target/.jar`）**。

而根本原因，正如您最终发现的那样，出在 abis-migrations-conversion 模块自身的 pom.xml 中：


  
    
      org.springframework.boot
      spring-boot-maven-plugin
      
      
        com.hcb.neurotec.migrations.conversion.AbisExportConverter
      
      
        
          
            repackage

? 为什么这会导致下游编译失败？

spring-bo

ot-maven-plugin:repackage 目标会：

覆盖默认的 maven-jar-plugin 行为；
尝试将普通 JAR 重打包为 fat-jar（含嵌入式 Tomcat、Spring Boot Loader 等）；
若项目缺少 spring-boot-starter-parent 或关键 Spring Boot 依赖（如 spring-boot-starter），repackage 阶段可能静默失败或生成不兼容标准 Java 类路径结构的 JAR（例如 MANIFEST.MF 缺失 Class-Path、或 classes 被嵌套在 BOOT-INF/classes/ 下）；
更严重的是：当 repackage 执行失败（但 Maven 未中断构建），maven-jar-plugin 的默认 jar 目标可能被跳过，导致 target/abis-migrations-conversion-1.0-SNAPSHOT.jar 根本未生成，或内容为空/损坏。

因此，当 runtime-migrations-conversion 执行 compile 阶段时，Maven 在本地仓库（~/.m2/repository/...）中查找不到有效的 abis-migrations-conversion-1.0-SNAPSHOT.jar，或找到的 JAR 不含 com/hcb/neurotec/migrations/conversion/ 下的 .class 文件，从而触发全面的编译失败。

✅ 正确解决方案

移除 abis-migrations-conversion 模块中所有与 Spring Boot 相关的插件配置，除非它确实是一个 Spring Boot 应用：

✅ 保留其标准 Maven 构建行为即可。该模块只需输出标准的、符合 Java EE 规范的 JAR（即 target/classes/ 内容被打包进 target/abis-migrations-conversion-1.0-SNAPSHOT.jar 的根路径下），下游模块才能通过 compile 正常引用。

? 验证与最佳实践

清理并验证依赖模块构建结果：
在修改 abis-migrations-conversion/pom.xml 后，单独执行：
```
cd abis-migrations-conversion
mvn clean install -X  # 加 -X 查看详细日志，确认 jar 插件执行成功
```
检查 target/abis-migrations-conversion-1.0-SNAPSHOT.jar 是否存在，并解压确认 com/hcb/neurotec/migrations/conversion/ 包路径下的 .class 文件已就位。
确保多模块构建顺序：
在项目根目录运行 mvn clean install 时，Maven 会按声明顺序构建，但更可靠的方式是显式指定构建顺序或使用 -pl 参数：
```
mvn clean install -pl abis-migrations-conversion,runtime-migrations-conversion -am
# -am: also make (自动构建所依赖的模块)
```
避免“伪 Spring Boot”配置：
若模块仅需 @SpringBootApplication 注解（如作为工具类启动器），但不发布为 Web 服务或无需 fat-jar，请勿引入 spring-boot-maven-plugin；可改用标准 maven-jar-plugin 配置 Main-Class：
```
  org.apache.maven.plugins
  maven-jar-plugin
  3.3.0
  
    
      
        com.hcb.neurotec.migrations.conversion.AbisExportConverter
      
    
  
```