本文详解 Spring Boot 多模块 Maven 项目中因 common-service 等内部模块依赖未被正确识别导致的编译失败问题，重点解决 package does not exist 和 cannot find symbol 错误，并给出可复现、可验证的配置修正方案。
本文详解 spring boot 多模块 maven 项目中因 `common-service` 等内部模块依赖未被正确识别导致的编译失败问题，重点解决 `package does not exist` 和 `cannot find symbol` 错误，并给出可复现、可验证的配置修正方案。
在 Spring Boot 多模块项目中，模块间依赖（如 account-service 引用 common-service 中的 Response、Constants、ErrorCodes 等类）本应通过 Maven 的 reactor 构建机制自动解析——前提是构建顺序、依赖声明与插件配置均严格符合约定。然而，您遇到的典型错误：
[ERROR] /.../UserController.java:[3,39] package com.hh.sukku.common.util does not exist [ERROR] /.../UserController.java:[50,31] cannot find symbol symbol: class Response
根本原因并非代码或包路径错误，而是 Maven 插件作用域配置不当，导致子模块编译时无法感知父 POM 中声明的编译器与构建插件配置。
? 问题定位：pluginManagement 缺失是关键症结
观察您的 hh/pom.xml（父 POM），虽然已声明 maven-compiler-plugin 和 spring-boot-maven-plugin，但它们被置于 <build><plugins> 下——这意味着这些插件仅对父模块 hh 自身生效。而 account-service、common-service 等子模块作为独立的 <packaging>jar</packaging> 工程，在编译时不会继承 <plugins> 中的配置，只能继承 <pluginManagement> 中的“模板”。
因此，当 account-service 执行 compile 阶段时：
- 它使用的是 Maven 默认的 JDK 编译器（可能版本不匹配）；
- 更严重的是，它完全忽略了父 POM 中为统一 Java 版本（1.8）所设的 <source>/<target> 配置；
- 导致 common-service 编译生成的字节码与 account-service 期望的类路径结构不一致，最终触发 package does not exist —— 实际上，common-service 的类文件虽已生成，但因编译器行为不一致或依赖解析链断裂，account-service 的编译器根本无法在 classpath 中定位其输出。
✅ 正确做法：将所有供子模块复用的插件配置移入 <pluginManagement> 块，确保子模块可通过 <plugins>（空声明）或隐式继承获得标准化行为。
✅ 正确修复：在父 POM 中启用 pluginManagement
将 hh/pom.xml 中的 <build><plugins> 块整体包裹进 <pluginManagement>，并保持子模块 pom.xml 不额外声明插件（除非需覆盖）：
<!-- hh/pom.xml -->
<build>
<pluginManagement> <!-- ✅ 关键：启用插件管理 -->
<plugins>
<!-- 统一编译器配置，强制所有子模块使用 JDK 1.8 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version> <!-- 显式指定版本，避免继承旧版 -->
<configuration>
<source>1.8</source>
<target>1.8</target>
<encoding>UTF-8</encoding>
</configuration>
</plugin>
<!-- Spring Boot 重打包插件（子模块若为 jar/war 可按需启用） -->
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>2.3.4.RELEASE</version>
<configuration>
<excludes>
<exclude>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</exclude>
</excludes>
</configuration>
</plugin>
</plugins>
</pluginManagement>
<!-- ⚠️ 注意：此处不再放 <plugins>，除非父模块自身需要执行特定目标 -->
</build>同时，确保每个子模块（如 account-service/pom.xml）显式声明对 common-service 的依赖（您已正确做到）：
<!-- account-service/pom.xml -->
<dependency>
<groupId>com.hh.sukku</groupId>
<artifactId>common-service</artifactId>
<version>${project.version}</version> <!-- ✅ 使用 ${project.version} 保证版本同步 -->
</dependency>? 验证构建流程（推荐顺序）
执行以下命令，严格遵循 Maven reactor 依赖顺序：
# 1. 清理本地仓库中可能损坏的快照（尤其重要！） mvn clean -Dmaven.repo.local=./.m2-local # 2. 全量构建：确保 common-service 先编译并安装到本地仓库 mvn clean install -Dmaven.repo.local=./.m2-local # 3. 单独验证 account-service（跳过已成功模块） mvn clean compile -pl :account-service -am -Dmaven.repo.local=./.m2-local
? -am（--also-make）参数确保 common-service 被自动构建；-pl（--projects）精准指定目标模块。这是排查多模块依赖问题的黄金组合。
⚠️ 其他高危陷阱与规避建议
| 问题类型 | 表现 | 解决方案 |
|---|---|---|
| IDE 缓存干扰 | IDEA 中无报错，但 mvn compile 失败 | 执行 File → Invalidate Caches and Restart，并关闭 "Build project automatically" |
| Lombok 注解未处理 | @Data, @AllArgsConstructor 等导致编译失败 | 在 common-service 和 account-service 的 pom.xml 中显式添加 Lombok 依赖（即使父 POM 声明了，子模块仍需 <optional>true</optional>）： <dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency> |
| Spring Boot Parent 版本过旧 | Spring Boot 2.3.4.RELEASE（2020年发布）存在已知 AOT 兼容性问题 | 强烈建议升级至 Spring Boot 2.7.x 或 3.2+（需同步升级 JDK 至 17+），新版对多模块依赖解析更健壮。 |
| 404 接口问题 | 应用启动成功但 API 返回 404 | 检查 application-service 是否正确 @SpringBootApplication 并扫描 account-service 包： @SpringBootApplication(scanBasePackages = "com.hh.sukku") |
✅ 总结：构建可靠性的三大支柱
- <pluginManagement> 是多模块项目的基石：它不是可选项，而是强制规范——所有影响编译、测试、打包行为的插件，必须在此声明。
- mvn clean install 必须成功且顺序可控：common-service 必须在 account-service 之前完成 install，确保其 JAR 被写入本地仓库（~/.m2/repository/com/hh/sukku/common-service/1.0.0/）。
- 拒绝“IDE 能跑即正确”的幻觉：IDE 的增量编译与 Maven 的全量生命周期本质不同。一切以 mvn clean compile 命令行结果为准。
遵循以上方案，您的 account-service 将能稳定编译并正确解析 common-service 的所有包与类，彻底终结 package does not exist 报错，为后续 Spring Boot Native Image 编译、微服务部署打下坚实基础。
