从‘程序包不存在’到成功打包：IntelliJ IDEA + Maven多模块项目实战避坑全记录

那天下午，当我第17次点击IntelliJ IDEA的Maven面板上的install按钮时，控制台再次弹出刺眼的红色错误："程序包com.example.common.utils不存在"。作为一个重构过多个单体应用的老手，这个看似简单的依赖问题却让我在工位前坐了整整三个小时。本文将完整还原这次多模块项目重构中的典型陷阱，以及比"加个skip配置"更本质的解决方案。

1. 当IDEA编译通过但Maven打包失败时

重构前的电商系统是个典型的Spring Boot单体应用，所有功能模块都挤在同一个代码库中。随着业务扩展，我们决定将其拆分为多模块Maven项目：common-utils（公共工具）、order-service（订单服务）、product-service（商品服务）等。在IDEA中，各模块间的代码跳转和编译一切正常，但执行 mvn install 时却报出"找不到符号"错误。

关键现象对比：

环境	编译结果	依赖解析方式
IDEA	成功	直接读取模块源码
Maven打包	失败	依赖本地仓库中的jar包

这个差异揭示了多模块开发的第一条铁律： IDEA的即时编译和Maven的仓库机制是两套不同的依赖系统 。当我们在子模块A中引用子模块B时：

1. IDEA会直接读取模块B的 target/classes 目录
2. Maven则要求模块B必须先将jar包安装到本地仓库

提示：遇到类似问题时，先用 mvn dependency:tree 检查依赖树，再用 ls ~/.m2/repository/ 确认jar包是否真的存在

2. Spring Boot打包机制的隐藏陷阱

通过 mvn install -X 开启调试日志后，发现在构建common-utils模块时，Maven实际上生成了两个jar文件：

common-utils-1.0.0.jar        // 普通jar（包含.class文件）
common-utils-1.0.0-exec.jar   // 可执行jar（包含Spring Boot加载器）

问题本质 ：Spring Boot的打包插件会默认生成可执行jar，并覆盖标准的jar包。而其他模块需要的是包含原始class文件的普通jar。

jar类型	内容结构	适用场景
普通jar	纯class文件	被其他模块依赖
可执行jar	BOOT-INF/classes结构	独立运行

3. 三种解决方案的深度对比

3.1 skip模式（最简方案）

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <skip>true</skip>
    </configuration>
</plugin>

适用场景 ：纯工具模块，不需要独立运行
缺点 ：彻底禁用Spring Boot打包功能

3.2 classifier模式（推荐方案）

<configuration>
    <classifier>exec</classifier>
</configuration>

这会生成两个独立文件：

• common-utils-1.0.0.jar（普通jar）
• common-utils-1.0.0-exec.jar（可执行jar）

优势 ：同时支持依赖和独立运行
验证命令 ：

mvn clean install
ls target/*.jar | grep -v original

3.3 自定义分类器（高级用法）

<configuration>
    <classifier>${project.classifier}</classifier>
</configuration>

在父pom中定义属性：

<properties>
    <project.classifier>exec</project.classifier>
</properties>

团队协作价值 ：统一所有子模块的打包规范

4. 多模块项目的最佳实践

在解决这个核心问题后，我们还整理出一套完整的避坑指南：

1. 父pom设计原则 ：
   • 统一所有子模块的Spring Boot版本
   • 集中管理公共依赖的版本号
   • 配置默认的Maven编译器参数

<!-- 示例父pom片段 -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>${spring-boot.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

2. 模块间依赖规范 ：

   • 避免循环依赖
   • 公共代码抽离到common模块
   • 服务模块保持最小依赖

3. 持续集成优化 ：

   • 并行构建模块加速CI流程
   • 缓存Maven本地仓库
   • 增量构建策略配置

5. 那些年我们踩过的其他坑

在实际迁移过程中，还有一些容易被忽略的细节：

资源文件加载问题 ：

• Maven多模块项目中，资源文件路径需要从 src/main/resources 调整为 classpath:/
• 测试资源文件需要特殊配置：

<testResources>
    <testResource>
        <directory>src/test/resources</directory>
        <filtering>true</filtering>
    </testResource>
</testResources>

IDE特定问题 ：

1. IntelliJ有时会错误缓存模块依赖，需要：
   • 执行 File -> Invalidate Caches
   • 重新导入Maven项目
2. 当修改父pom后，需要：
   • 先install父项目
   • 再处理子模块

一个真实案例 ：某次在order-service中引入product-service后，运行时却报NoClassDefFoundError。最终发现是因为product-service的pom中漏掉了必要的传递依赖。这促使我们在团队内推行了新的依赖审查流程：

1. 新增依赖必须说明用途
2. 每周进行依赖树分析
3. 使用Maven Enforcer插件约束依赖规范

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-enforcer-plugin</artifactId>
    <executions>
        <execution>
            <id>enforce-versions</id>
            <goals>
                <goal>enforce</goal>
            </goals>
            <configuration>
                <rules>
                    <requireJavaVersion>
                        <version>[1.8,)</version>
                    </requireJavaVersion>
                </rules>
            </configuration>
        </execution>
    </executions>
</plugin>

这次重构经历让我深刻体会到：在多模块项目中， 构建工具的正确配置与团队规范同样重要 。现在我们的CI流水线上增加了一个特殊的检查步骤——确保每个模块生成的jar包类型符合预期。这看似多余的检查，已经帮我们提前发现了三次潜在的依赖问题。