本文详解 jacoco 在 maven 多模块项目中 `report-aggregate` 不生效的根本原因——子模块缺失 `prepare-agent` 配置、`argline` 被覆盖导致 `.exec` 文件未生成，并提供可落地的父子模块协同配置方案。
在 Maven 多模块项目中，使用 JaCoCo 进行跨模块代码覆盖率聚合（report-aggregate）时，一个常见却极易被忽视的问题是：聚合报告看似生成，但各子模块的覆盖率数据缺失或错位——例如 module1 的报告中只显示 module2 和 module3 的覆盖数据，自身代码完全未被统计。这并非 JaCoCo 的 Bug，而是由其执行机制与 Maven 生命周期绑定方式决定的。
根本原因解析
JaCoCo 的 report-aggregate 本身不执行测试，也不收集覆盖率数据；它仅合并已存在的 jacoco.exec 文件（默认位于各子模块的 target/jacoco.exec）。因此，必须确保：
- 每个子模块均独立启用 prepare-agent（注入 JVM 参数以生成 .exec）；
- 父模块（聚合模块）不参与测试执行，仅负责聚合；
- argLine 必须正确继承与拼接——若子模块 POM 中手动覆写了 <argLine>（如添加 -XX:MaxPermSize），会完全覆盖 JaCoCo 注入的参数，导致 .exec 文件无法生成。
⚠️ 注意：report-aggregate 只能聚合 已构建完成且包含有效 .exec 文件 的子模块。若某模块跳过测试（如 maven.test.skip=true）或 argLine 被覆盖，则其 .exec 为空/不存在，聚合时自动忽略。
正确配置方案
✅ 步骤 1：在所有子模块（module1, module2, module3）的 pom.xml 中配置 prepare-agent
<build>
<plugins>
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>0.8.8</version>
<executions>
<!-- 关键：为每个子模块启用 agent -->
<execution>
<id>default-prepare-agent</id>
<goals>
<goal>prepare-agent</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>✅ 步骤 2：在父模块（DEF/pom.xml）中配置 report-aggregate（仅聚合，不执行 prepare-agent）
<build>
<plugins>
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>0.8.8</version>
<executions>
<!-- 父模块不执行 prepare-agent -->
<execution>
<id>report-aggregate</id>
<phase>verify</phase> <!-- 推荐用 verify，确保所有子模块已构建完成 -->
<goals>
<goal>report-aggregate</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/reports/jacoco-aggregate</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>✅ 步骤 3：安全处理 argLine（避免覆盖 JaCoCo 参数）
若子模块需自定义 JVM 参数（如内存设置），必须使用 ${argLine} 占位符拼接，而非直接重写：
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<!-- ✅ 正确：前置拼接，保留 JaCoCo 的 -javaagent -->
<argLine>${argLine} -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8</argLine>
</configuration>
</plugin>❌ 错误示例（将导致 .exec 不生成）：
<argLine>-XX:MaxMetaspaceSize=512m</argLine> <!-- 完全覆盖！JaCoCo agent 丢失 -->
验证与调试技巧
-
检查 .exec 文件是否存在
执行 mvn clean test 后，确认每个子模块目录下存在非空的 target/jacoco.exec：ls -lh DEF/module1/target/jacoco.exec ls -lh DEF/module2/target/jacoco.exec
-
启用 JaCoCo 调试日志
添加 -X 参数运行 Maven，搜索 argLine 输出，确认 -javaagent: 已注入：mvn clean test -X | grep "argLine"
-
强制生成聚合报告
单独执行聚合生命周期（跳过测试）：mvn jacoco:report-aggregate -f DEF/pom.xml
总结
JaCoCo 多模块覆盖率的核心原则是：数据采集（prepare-agent）分散在子模块，数据聚合（report-aggregate）集中于父模块。任何环节的断链（子模块无 agent、argLine 覆盖、生命周期阶段错误）都会导致聚合失效。务必遵循“子模块配 agent + 父模块配 aggregate + argLine 安全拼接”三要素，并通过验证 .exec 文件存在性快速定位问题。此方案兼容 JaCoCo 0.8.x 及 0.9.x 版本，适用于标准 Maven 聚合项目结构。
