本文详解 jacoco 在 maven 多模块项目中 `report-aggregate` 失效的典型原因（如子模块缺失自身覆盖率、`jacoco.exec` 未生成），并提供可落地的插件配置、`argline` 安全继承方案及完整验证步骤。
在 Maven 多模块项目中（如 DEF 根模块下包含 module1、module2、module3），仅在根 pom.xml 中配置 JaCoCo 的 report-aggregate 并不能自动获得准确的聚合覆盖率报告——常见现象是：各子模块目录下生成了独立报告，但 module1 的报告中却缺失其自身代码的覆盖率数据，反而混入了 module2 或 module3 的指标；更严重时，某个模块甚至完全不生成 target/jacoco.exec 文件。这并非 JaCoCo 功能缺陷，而是由执行作用域错位与JVM 参数覆盖冲突导致。
✅ 正确配置原则：根模块声明 + 子模块继承 + 参数安全合并
JaCoCo 的 report-aggregate 目标本身不执行测试，它仅汇总已存在的 jacoco.exec 文件。因此必须确保：
- 所有子模块均通过 prepare-agent 注入探针，并生成各自的 jacoco.exec；
- 根模块的 report-aggregate 能扫描到全部子模块的 exec 文件（默认递归查找）；
- 各子模块若自定义了 maven-surefire-plugin 的
，必须显式继承父级 JaCoCo 的 JVM 参数，否则探针失效。
✅ 推荐根模块 pom.xml 配置（DEF/pom.xml）
<build>
<plugins>
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>0.8.11</version> <!-- 建议升级至 0.8.11+（修复多模块路径问题） -->
<executions>
<!-- 为所有子模块启用探针注入 -->
<execution>
<id>default-prepare-agent</id>
<goals>
<goal>prepare-agent</goal>
</goals>
</execution>
<!-- 在根模块聚合报告 -->
<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>⚠️ 注意：prepare-package 不推荐——此时 surefire:test 可能尚未执行，jacoco.exec 文件不存在，导致聚合为空。
✅ 关键：子模块需继承并安全扩展 argLine
若任一子模块（如 module1）在 pom.xml 中自定义了 maven-surefire-plugin 并覆盖
<!-- module1/pom.xml 中的 surefire 配置 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<!-- ✅ 安全继承：${argLine} 是 JaCoCo prepare-agent 自动注入的参数 -->
<argLine>${argLine} -XX:PermSize=256m -XX:MaxPermSize=1048m</argLine>
</configuration>
</plugin>✅ 验证方式：运行 mvn clean verify 后，检查每个子模块的 target/jacoco.exec 是否存在（非空文件），再确认根目录下 target/reports/jacoco-aggregate/index.html 是否包含全部模块的类、行、分支覆盖率。
? 常见陷阱与排查清单
- ❌ 错误：仅在根模块配 report-aggregate，子模块未启用 prepare-agent → 解决：确保子模块未禁用父 POM 的 JaCoCo 插件（检查
是否过度限制）。 - ❌ 错误：子模块 surefire 配置中硬编码
-Xmx2g → 解决：必须写成 ${argLine} -Xmx2g。 - ❌ 错误：使用 forkMode=never（旧版 Surefire）或 forkCount=0 → JaCoCo 探针无法注入 → 解决：启用 fork（默认行为即可）。
- ✅ 进阶建议：在根模块添加
0.8.11
最终，一个健壮的多模块 JaCoCo 配置 = 统一插件声明 + 显式 argLine 继承 + verify 阶段聚合。执行一次 mvn clean verify，即可在根模块获得真正反映全项目健康度的聚合覆盖率报告。
