本文详解如何在 maven 多模块项目中正确配置 jacoco 插件，解决 `report-aggregate` 生成错误（如子模块报告缺失自身覆盖率、`jacoco.exec` 文件未生成）等常见问题，并提供可直接复用的配置方案与关键注意事项。
在 Maven 多模块项目中集成 JaCoCo 进行全量代码覆盖率分析时，一个典型误区是：仅在父 POM 中配置 jacoco-maven-plugin 并使用 report-aggregate，却忽略了子模块的执行上下文与 JVM 参数协同机制。这会导致聚合报告内容错乱——例如 module1 的报告中缺失其自身覆盖率，反而包含 module2/module3 的数据；更严重时，部分模块甚至完全不生成 target/jacoco.exec 执行数据文件，致使聚合失败。
根本原因在于两点：
-
prepare-agent 执行范围不明确：若未显式指定
中的 propertyName 或依赖 argLine 传递机制，JaCoCo Agent 可能无法正确注入到各子模块的测试 JVM 中； -
被覆盖或丢失 ：当子模块 POM 中已定义（如用于内存调优、系统属性等），而父模块未做兼容性合并，将导致 JaCoCo Agent 启动参数被完全覆盖，jacoco.exec 文件无法生成。
✅ 正确配置应遵循“父模块声明 + 子模块继承 + 安全参数合并”三原则。以下是经过验证的生产级配置方案：
✅ 父 POM（DEF/pom.xml）推荐配置
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>0.8.11</version> <!-- 建议升级至 0.8.11+（兼容 JDK 17+，修复旧版聚合 Bug） -->
<executions>
<!-- 为所有子模块启用 agent 注入 -->
<execution>
<id>default-prepare-agent</id>
<goals>
<goal>prepare-agent</goal>
</goals>
<!-- 关键：通过 property 传递 argLine，避免直接覆盖子模块原有配置 -->
<configuration>
<propertyName>jacocoArgLine</propertyName>
</configuration>
</execution>
<!-- 聚合报告：必须在父模块执行，且 phase 设为 prepare-package 或 verify -->
<execution>
<id>report-aggregate</id>
<phase>verify</phase>
<goals>
<goal>report-aggregate</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/reports/jacoco-aggregate</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>✅ 子模块 POM（如 module1/pom.xml）必须补充
确保每个子模块的 maven-surefire-plugin 正确引用父模块传递的 jacocoArgLine：
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.2.5</version>
<configuration>
<!-- 安全合并：保留原有 argLine，追加 JaCoCo 参数 -->
<argLine>${jacocoArgLine} ${argLine}</argLine>
<!-- 其他配置（如 forkMode, systemProperties）可继续添加 -->
</configuration>
</plugin>⚠️ 关键注意事项： 若子模块已有 （如 -Xmx2g -Dfile.encoding=UTF-8），必须写成 ${jacocoArgLine} ${argLine}（顺序不可颠倒），否则 JaCoCo 参数将被丢弃； 不要手动在子模块中重复配置 jacoco-maven-plugin，除非需定制单模块报告（此时需禁用父模块的 default-prepare-agent 继承）； 运行聚合命令时，务必在父目录执行：mvn clean verify（而非 mvn jacoco:report-aggregate 单独调用），确保 prepare-agent 和测试执行完整链路触发； 验证 jacoco.exec 是否生成：检查每个子模块的 target/jacoco.exec 文件是否存在且非空（大小 > 0）； 若仍出现报告缺失，启用调试日志：mvn verify -X | grep -i jacoco，确认 prepare-agent 是否为每个子模块执行。
最终，成功执行后将在 DEF/target/reports/jacoco-aggregate/ 下生成包含所有子模块（module1, module2, module3）源码、测试覆盖率及聚合指标的 HTML 报告，各模块数据独立准确、无交叉污染。该配置已在 Maven 3.8+、JDK 8–21 环境下稳定运行，适用于 Spring Boot、Quarkus 等主流框架的多模块工程。
