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 中：

<build>
  <plugins>
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
      <!-- ⚠️ 问题所在：该模块并非 Spring Boot 应用 -->
      <configuration>
        <mainClass>com.hcb.neurotec.migrations.conversion.AbisExportConverter</mainClass>
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>repackage</goal> <!-- 此 goal 强制要求项目为可执行 Spring Boot Jar -->
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

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

spring-boot-maven-plugin:repackage 目标会：

Unscreen

AI智能视频背景移除工具

下载

• 覆盖默认的 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 应用：

<!-- ❌ 删除整个 spring-boot-maven-plugin 块 -->
<!-- <plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
  ...
</plugin> -->

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

? 验证与最佳实践

1. 清理并验证依赖模块构建结果：
   在修改 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 文件已就位。

2. 确保多模块构建顺序：
   在项目根目录运行 mvn clean install 时，Maven 会按 声明顺序构建，但更可靠的方式是显式指定构建顺序或使用 -pl 参数：

   mvn clean install -pl abis-migrations-conversion,runtime-migrations-conversion -am
   # -am: also make (自动构建所依赖的模块)

3. 避免“伪 Spring Boot”配置：
   若模块仅需 @SpringBootApplication 注解（如作为工具类启动器），但不发布为 Web 服务或无需 fat-jar，请勿引入 spring-boot-maven-plugin；可改用标准 maven-jar-plugin 配置 Main-Class：

   <plugin>
     <groupId>org.apache.maven.plugins</groupId>
     <artifactId>maven-jar-plugin</artifactId>
     <version>3.3.0</version>
     <configuration>
       <archive>
         <manifest>
           <mainClass>com.hcb.neurotec.migrations.conversion.AbisExportConverter</mainClass>
         </manifest>
       </archive>
     </configuration>
   </plugin>

? 总结：Maven 的依赖解析严格基于构件（JAR）而非源码。IDE 的智能感知 ≠ Maven 构建成功。排查此类问题，请始终优先检查依赖模块是否真正生成了合法、可用的 JAR 包，并警惕“过度配置”（如给普通库项目添加 Spring Boot 插件）引发的构建链路断裂。