多模块Maven项目JaCoCo覆盖率聚合的5类典型坑与排查指南

做 Java 后端这些年每次项目从单模块往多模块迁移最容易被忽略的不是业务代码本身而是覆盖率统计这一整套东西。单模块下 JaCoCo 跑得好好的mvn test结束自动生成一份漂亮的 HTML 报告看起来一切都很正常。一旦拆成父 POM 多个子模块的结构再按原来的方式配置一遍问题就接踵而来聚合报告空白、只有某个模块的数据、点进类看不到源码、CI 上报告和本地长得不一样。这篇文章我把踩过的 5 类坑完整复盘一遍每一条都包含现象、排查链路和最终落地的配置适合正在做多模块改造、或者准备搭建覆盖率门禁的团队直接对照排查。1. 从单模块到多模块聚合报告到底在聚合什么1.1 JaCoCo 报告生成的三个必需品聊坑之前先把 JaCoCo 的工作链条理清楚。一份 JaCoCo 报告要正常生成必须凑齐三样东西exec文件、class 文件和 source 文件。exec文件是测试运行时的证据。prepare-agent目标会在 Maven 的测试 JVM 启动参数里塞一段-javaagent这段 agent 会记录每一行指令、每一个分支是否被执行JVM 停止时把结果写到jacoco.exec。class 文件是被测代码的编译产物JaCoCo 需要拿它做字节码分析最终算出指令覆盖率、分支覆盖率、圈复杂度这些指标。source 文件则纯粹是为了报告展示HTML 报告里那个能点击查看源码的功能靠的就是它。这三样东西的关系有点像做工程验收exec是施工日志class 是实际结构source 是设计图纸。单模块项目里这三样天然放在同一个目录下prepare-agent生成的exec在当前模块的targetclass 也在当前模块的target/classessource 就在src/main/java。所以单模块几乎不需要任何额外配置装好插件就能出报告。1.2 单模块能跑通多模块为什么就崩多模块的难点在于聚合报告需要把 N 个模块的三样东西汇集到同一份报告里。这时候就牵涉到几个单模块时代根本不会考虑的问题每个模块的exec文件在哪生成什么时候生成聚合目标是从哪个模块去扫描其它模块的数据模块之间的依赖关系、构建顺序会不会影响数据读取说实话很多人踩坑并不是因为 JaCoCo 有多复杂而是因为多模块构建里Maven 的 reactor 机制、插件配置继承、属性解析顺序互相交织任何一个环节没对齐结果都会静默出错——注意是静默JaCoCo 很少会直接报 fatal error它更倾向于生成一份看起来正常但数据不完整的报告。这种问题最磨人因为日志不会告诉你答案。1.3 后面五个坑的排查路径总览我把多模块报告聚合最常见的五个问题按根因分了类方便你先有个全局认识坑点核心症状根因类别坑点一聚合报告空白或 0%测试明明跑了argLine参数被覆盖agent 没进入测试 JVM坑点二报告只有单模块数据或输出目录不对report和report-aggregate目标混用坑点三报告缺了某几个模块无人报错聚合模块没有声明对目标模块的依赖坑点四覆盖率数字有源码点开一片红class/source 路径解析失效坑点五换台机器、换个流水线结果就变插件版本不统一、构建时序失控下面逐一拆解。2. 坑点一argLine 被上层配置覆盖exec 文件直接缺失2.1 现象与复现路径这个坑我最早是在一个子模块数量超过 20 的工程里碰到的。当时 CI 上聚合报告突然全部显示 0%本地怎么跑都正常。检查了相当久最后发现是基础父 POM 里加了一段 JVM 参数配置把argLine属性整个覆盖了。这里要先解释一个机制prepare-agent不会直接修改 JVM它只是往 Maven 的一个属性里写入 agent 参数默认这个属性名就是argLine。真正启动测试 JVM 的是maven-surefire-plugin它读取argLine属性作为测试 JVM 的启动参数。所以完整的链路是prepare-agent设置argLine属性 → surefire 读取argLine→ 测试 JVM 带上 agent → 测试跑完生成exec。问题就出在设置和读取之间。任何一方对argLine做了重复定义都可能让 agent 参数被冲掉。最常见的两种父 POM 的properties里定义了argLine-Xmx1024m/argLine这个值会把prepare-agent写入的值覆盖掉。某个模块的maven-surefire-plugin配置里直接写了argLine-Xmx1024m/argLine且没有带上{argLine}占位符。结局都一样测试 JVM 里根本没有 JaCoCo agent测试照样跑但target/jacoco.exec永远不会生成。聚合报告读不到exec自然只能给你一张全白或全 0 的图。2.2 排查链路从文件缺失到参数覆盖如果你也遇到报告空白但测试正常的情况按这个顺序查在项目根目录执行find . -name *.exec -exec ls -l {} \;看看哪些模块生成了exec哪些没有。如果几乎所有模块都没有基本可以锁定是 agent 没有注入。找一个没生成exec的模块执行mvn help:evaluate -DexpressionargLine -q -DforceStdout看当前模块解析出来的argLine是什么。如果输出里没有javaagent相关路径说明这个属性确实被业务配置占了。打开这个模块的mvn help:effective-pom重点看maven-surefire-plugin的argLine配置和父 POM 的properties。顺手看一眼target/surefire-reports目录的生成时间排除测试压根没跑到的可能性。这里有个小技巧第 2 步的help:evaluate必须在具体模块目录下执行因为多模块每个子模块可能从不同的父 POM 继承了不同属性。在根目录执行只能看到根 POM 的解析结果可能会误导你。2.3 标准解法与验证方式解法不唯一但思路是一致的保证prepare-agent写入的 agent 参数能原封不动地传给 surefire。推荐做法是在父 POM 里统一管理 JaCoCo 插件版本properties jacoco.version0.8.12/jacoco.version /properties build pluginManagement plugins plugin groupIdorg.jacoco/groupId artifactIdjacoco-maven-plugin/artifactId version${jacoco.version}/version /plugin /plugins /pluginManagement /build然后在确实需要跑测试的子模块或者直接在父 POM 的build里让所有子模块继承加入plugin groupIdorg.jacoco/groupId artifactIdjacoco-maven-plugin/artifactId executions execution iddefault-prepare-agent/id goals goalprepare-agent/goal /goals /execution /executions /plugin同时任何自定义 JVM 参数都不要直接放在properties里而是放到 surefire 的argLine中并保留{argLine}占位符plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-surefire-plugin/artifactId version3.2.5/version configuration argLine{argLine} -Xmx1024m/argLine /configuration /plugin{argLine}是 Maven 3.2.1 之后的延迟解析语法。它会在 surefire 真正执行插件配置时才去解析属性值这时候prepare-agent已经运行完argLine里带着完整的 agent 参数所以最终拼接出来的就是agent 参数 你的业务参数。验证是否修复很简单重新执行mvn clean test再次用find检查各模块target下是否生成了jacoco.exec。每个模块的exec文件大小应该在几十 KB 到几 MB 之间如果发现某个模块的exec只有几百字节基本可以断定这个模块没有正常采集数据。注意排查这类问题时别一上来就怀疑 JaCoCo 版本。exec 文件格式的兼容性整体是好的大部分数据互不认账的案例真正的原因都是 agent 没注入或者配置被覆盖。3. 坑点二report 与 report-aggregate 目标选错报告形态南辕北辙3.1 两个 goal 的工作边界差异很多博客只教你在 POM 里配 jacoco-maven-plugin然后执行mvn test就会出报告不会告诉你这个配置下默认触发的是report目标。report和report-aggregate虽然都是生成覆盖率报告但工作边界完全不同。目标处理范围默认输出目录适用场景report当前 Maven 项目自身的数据target/site/jacoco单模块项目report-aggregate当前项目及其依赖的本地模块target/site/jacoco-aggregate多模块聚合report只关心当前 Maven 项目上下文里的exec、class、source。如果当前项目是一个packagingpom的父模块它既没有测试也没有 class 文件report执行时只会输出一行类似Skipping JaCoCo execution due to missing classes directory的日志然后什么都不生成。这段日志非常具有迷惑性因为它不报错只会在 verbose 日志里出现一行。report-aggregate则会去扫描当前项目声明的本地依赖把这些依赖模块的exec、class、source全部找出来汇总成一份跨模块报告。这才是多模块场景真正需要的目标。3.2 现象与排查链路这个坑的典型现象是在根 POM 配了插件执行mvn verify耗时也很正常看起来报告生成了但你去target/site下看只有jacoco目录或者根本没有聚合目录。打开 HTML要么只有父模块本身的数据通常为空要么只有某一个模块的数据。排查的时候先看输出目录target/site/jacoco存在 → 你执行的是report目标。target/site/jacoco-aggregate存在 → 你执行的是report-aggregate目标。再看构建日志留意有没有Skipping JaCoCo execution due to missing classes directory这类提示。如果日志里每个模块都打出了Site directory .../target/site/jacoco说明所有模块都各自执行了report这时候生成的是一堆分散的单模块报告不是聚合报告。最后用mvn help:effective-pom检查当前生效的插件配置确认executions里的goal到底是哪个。有时候根 POM 和子模块各配了一版子模块覆盖了根 POM 的配置就会出现根模块是 aggregate子模块却执行 report这种混合行为。3.3 正确的 plugin 配置示例多模块项目里标准做法是把聚合配置放在一个专门的聚合模块里或者直接放在父 POM 供所有模块继承。这里先给一个最直接的版本plugin groupIdorg.jacoco/groupId artifactIdjacoco-maven-plugin/artifactId executions execution idprepare-agent/id goals goalprepare-agent/goal /goals /execution execution idaggregate-report/id phaseverify/phase goals goalreport-aggregate/goal /goals /execution /executions /plugin如果你把这段配在父 POM 的buildplugins里所有子模块会继承prepare-agent和report-aggregate。每个模块测试时会生成自己的exec到了verify阶段每个模块会尝试执行一次report-aggregate聚合的是它自己依赖的那些模块数据。这会导致聚合报告在每个模块下都生成一份内容可能略有差异。如果你想要只在某一个地方产出一份完整聚合报告更推荐的做法是新建一个独立的聚合模块也就是下一个坑要说的核心方案。这里你只需要记住别再用report目标去做多模块聚合它的设计就不是干这个的。4. 坑点三聚合模块没有声明依赖report-aggregate 只扫到半张图4.1 现象报告缺模块却没人报错这个坑最坑的地方在于报告能正常生成但内容不完整。举个例子一个工程有mall-common、mall-service、mall-web三个子模块聚合报告里可能只有mall-web的数据另外两个模块死活不出现。而且构建日志没有任何红色报错看着就像mall-web本身的覆盖率。第一次遇到这个情况时我第一反应是某个子模块的exec没生成。逐个检查完所有exec都存在后又怀疑是不是版本问题。最后才发现根因在聚合模块的依赖声明上。4.2 原理report-aggregate 按依赖不按 modulesreport-aggregate的目标是读取当前项目依赖的本地模块数据。注意关键词是依赖。它并不是扫描modules列表而是分析当前 POM 的dependencies然后从这些依赖中挑出属于本地 reactor 的模块再读取它们的覆盖率数据。但很多多模块工程的父 POM 是这样的结构groupIdcom.example/groupId artifactIdmall-parent/artifactId packagingpom/packaging modules modulemall-common/module modulemall-service/module modulemall-web/module /modules父 POM 只声明了modules没有声明dependencies。从 Maven 视角看父模块和子模块之间是聚合关系aggregation不是依赖关系dependency。你在父 POM 上执行report-aggregate它找不到任何依赖的本地模块自然只能聚合出一份空报告或残缺报告。这也是很多教程让人新建聚合模块的根本原因聚合模块需要有一个合理的dependencies把这些业务模块真正依赖进来report-aggregate才有东西可扫。4.3 标准解法新增聚合模块我的习惯是在多模块工程里额外加一个专门的聚合模块名字通常叫coverage-report或aggregationpackaging设为pom。它的完整配置如下project parent groupIdcom.example/groupId artifactIdmall-parent/artifactId version1.0.0-SNAPSHOT/version /parent artifactIdcoverage-report/artifactId packagingpom/packaging dependencies dependency groupIdcom.example/groupId artifactIdmall-common/artifactId version${project.version}/version /dependency dependency groupIdcom.example/groupId artifactIdmall-service/artifactId version${project.version}/version /dependency dependency groupIdcom.example/groupId artifactIdmall-web/artifactId version${project.version}/version /dependency /dependencies build plugins plugin groupIdorg.jacoco/groupId artifactIdjacoco-maven-plugin/artifactId executions execution idaggregate-report/id phaseverify/phase goals goalreport-aggregate/goal /goals /execution /executions /plugin /plugins /build /project注意coverage-report模块不需要写modules它只需要声明依赖。构建时在根目录执行mvn clean verifyMaven 的 reactor 会按模块依赖顺序构建先构建mall-common、mall-service、mall-web最后构建coverage-report。到了coverage-report的verify阶段report-aggregate就能在当前构建上下文里找到这几个子模块的数据汇总出一份完整报告。最终报告输出在coverage-report/target/site/jacoco-aggregate/index.html打开就是全模块总览可以点击跳转到任意一个类的覆盖率详情。4.4 不新增模块时怎么处理如果你的项目结构已经定型不方便新增模块也有变通方案找一个恰好依赖了所有需要统计模块的业务模块把report-aggregate配置在那个模块上。比如mall-web依赖了mall-service和mall-common那直接在mall-web上执行report-aggregate就能聚合mall-web自身和它依赖的所有模块。但这种方式有两个隐患一是报告位置在业务模块的target/site下很容易在后续构建中被覆盖或清理二是如果以后某个模块不再被mall-web依赖它就会静默地从聚合报告里消失。所以我还是建议新增专门的聚合模块职责单一不会被业务依赖变更误伤。提示如果聚合报告里出现了大量第三方库的类比如 Spring 框架内部的类可以在report-aggregate的configuration里加excludes过滤掉避免分母把整体覆盖率拉低。5. 坑点四class 与 source 路径解析不准覆盖率数字里藏着幽灵源码5.1 现象数字在、源码失联第三种坑最让人困惑的地方在于报告的覆盖率数字看起来是正常的有百分比、有类列表、甚至能显示某个类的 80% 行被覆盖。但你想点进去看看哪些行没覆盖却提示找不到源码文件。或者更诡异一点同一个类在单模块报告里一切正常在聚合报告里却全部显示红色指令覆盖率归零。出现这种情况基本可以断定是report-aggregate在解析 class 或 source 路径时出了问题。它虽然从依赖模块找到了exec文件但没能正确关联到对应的 class 文件和 source 文件于是报告只能显示一个总覆盖率轮廓无法展示源码级别的行覆盖。5.2 排查链路从 jacoco.xml 里找线索JaCoCo 的 HTML 报告本质上是由jacoco.xml渲染出来的。遇到源码不显示的问题别急着眼花缭乱翻 HTML直接打开聚合目录下的jacoco.xml搜关键信息。jacoco.xml里每个类会记录它的class文件路径每个sourcefile节点会记录源码文件名。你搜索一个出问题的类看它对应的sourcefile nameOrderService.java/是否存在。如果sourcefile节点不存在说明聚合时压根没找到这个类的源码文件。接下来查看聚合报告target/site/jacoco-aggregate下有没有src目录以及目录里的包结构是否完整。如果src目录下是空的那就说明 source 路径没有传进来。另一边检查 class 文件的解析源。这里有一个很容易被忽略的坑report-aggregate在读取依赖模块的 class 时优先使用当前 reactor 上下文中模块的输出目录。如果你不在根目录执行全量构建而是在聚合模块目录下单独执行mvn verifyMaven 的 reactor 里只有coverage-report和它的父 POM其他业务模块不会出现在 reactor 中。这时候report-aggregate只能去本地仓库找依赖 jar从 jar 里读 class。本地仓库的 jar 可能是很久之前 install 的旧版本和你正在分析的项目代码对不上覆盖率自然不可信。5.3 解法与习惯建议标准解法其实很简单始终在根目录执行全量构建命令mvn clean verify不要只跑到mvn test也不要只跑到某个模块目录下单独执行verify。report-aggregate绑定在verify阶段全量构建能保证所有模块的exec、class、source都在同一个 reactor 上下文中聚合时不会因为缺文件而静默降级。如果你的项目确实用了非标准目录比如 Kotlin 项目把源码放在src/main/kotlin正常情况下kotlin-maven-plugin会把src/main/kotlin加入 Maven 的 compile source rootJaCoCo 能直接识别。但如果某个模块是自己用脚本或者build-helper-maven-plugin添加的额外源码目录聚合时可能识别不到。这种情况下可以给report-aggregate显式配置源码目录。plugin groupIdorg.jacoco/groupId artifactIdjacoco-maven-plugin/artifactId executions execution idaggregate-report/id phaseverify/phase goals goalreport-aggregate/goal /goals configuration sourceDirectories sourceDirectory${project.basedir}/src/main/kotlin/sourceDirectory /sourceDirectories /configuration /execution /executions /plugin依赖 Lombok 的项目这里也要多说一句Lombok 会在编译期生成大量样板方法JaCoCo 会把这些方法也统计进覆盖率。我见过不少团队因为 Lombok 生成的equals、hashCode没被测试覆盖导致项目的整体覆盖率莫名低了几个百分点。这类问题虽然不是路径解析直接引起的但如果聚合报告里幽灵类特别多很可能就是 Lombok 生成的代码。建议在 JaCoCo 配置里统一排除configuration excludes excludelombok.*/exclude exclude**/generated/**/exclude /excludes /configuration注意这个excludes配置同时作用于 class 分析和报告展示能有效过滤掉那些不属于你业务代码的噪音类。6. 坑点五版本与构建时序失控数据互相不认账6.1 现象换台机器、换个流水线结果就变了最后这个坑更像慢性病。它的典型表现是本地执行mvn verify生成的聚合报告数据是对的但 CI 上跑出来的覆盖率比本地低或者缺失了某几个模块的数据。有时候同一个 CI 流水线上一次跑和下一次跑结果还不一样。这种数据互相不认账的问题根因通常不是某个单一配置而是版本一致性和构建时序同时失控。6.2 排查链路exec 时间戳、effective-pom、skip 开关遇到结果不稳定按顺序查三样东西第一步先看所有模块的exec文件。执行find . -name *.exec -exec ls -l {} \;重点关注每个exec的时间戳和文件大小。如果某个模块的exec时间戳明显早于这次构建说明这个模块这次压根没跑测试或者测试中途被跳过了。如果某个模块的exec大小只有几百字节而其他模块都有几十 KB说明它的 agent 采集到的覆盖率数据严重偏少基本可以断定测试没有真正执行或者模块内有skip配置。第二步检查每个模块实际生效的插件版本。执行mvn help:effective-pom -Dverbose看各个模块的jacoco-maven-plugin和maven-surefire-plugin版本。如果不同模块显示的版本不一样优先检查父 POM 是否用了pluginManagement。pluginManagement只对声明了对应插件的子模块生效如果子模块自己单独声明了插件版本就会覆盖父 POM 的管理。第三步检查skip开关。多模块工程里很容易出现某些模块为了加速构建配置了跳过测试properties maven.test.skiptrue/maven.test.skip jacoco.skiptrue/jacoco.skip /propertiesmaven.test.skip会跳过测试编译当然也就没有覆盖率数据。jacoco.skip会跳过 JaCoCo 的 agent 注入测试会跑但不会生成exec。这两种情况都不会让聚合报告报错只是相应模块的数据从聚合里消失然后整体覆盖率被剩余模块拉平。6.3 标准解法统一版本、统一时序、必要时用 merge解法其实不复杂核心是两条原则。第一版本必须统一在父 POM 的pluginManagement里。比如pluginManagement plugins plugin groupIdorg.jacoco/groupId artifactIdjacoco-maven-plugin/artifactId version0.8.12/version /plugin /plugins /pluginManagement子模块不要自己声明版本只声明goal。这样所有模块的 agent 和 report 都是同一版本exec 文件的解析行为一致。第二时序必须统一。报告生成依赖测试已经跑完所以聚合目标必须绑定在verify阶段并且整个构建过程应该是一次完整的mvn clean verify。不要在 CI 里把跑测试和生成报告拆成两个独立 Job除非你能保证两个 Job 之间共享完整的构建产物文件。如果你确实因为多阶段流水线等原因必须拆分可以考虑用merge目标把多个模块的exec合并成一个文件。典型配置如下plugin groupIdorg.jacoco/groupId artifactIdjacoco-maven-plugin/artifactId executions execution idmerge-results/id phaseverify/phase goals goalmerge/goal /goals configuration fileSets fileSet directory${project.basedir}/directory includes include**/target/jacoco.exec/include /includes /fileSet /fileSets destFile${project.build.directory}/jacoco-aggregate.exec/destFile /configuration /execution /executions /plugin但merge目标只能合并exec数据它不负责收集 class 和 source。合并后的exec还需要配合report目标、并指定好 class 目录和 source 目录才能生成可读的聚合报告。所以merge更适合我已经有一份全部模块的 exec只是想合并体积或转换格式的场景日常多模块聚合还是优先用report-aggregate。6.4 别忘了 SonarQube 的场景如果你的覆盖率最终要推送到 SonarQube 之类平台还有一个相关的小坑SonarQube 扫描时并不会自动读取 JaCoCo 的聚合报告你需要显式告诉它 exec 文件的路径。多模块工程里通常这样配properties sonar.jacoco.reportPaths ${project.basedir}/../mall-common/target/jacoco.exec, ${project.basedir}/../mall-service/target/jacoco.exec, ${project.basedir}/../mall-web/target/jacoco.exec /sonar.jacoco.reportPaths /properties如果只填了根目录的target/jacoco.execSonarQube 扫描多模块时大概率只能拿到一个模块的数据这也是报告和平台数据对不上的常见原因。7. 给团队的快速排查清单从症状直接锁定根因7.1 速查表最后把五个坑浓缩成一张速查表排查的时候对应着看能省不少时间。症状最可能的根因第一条检查命令报告空白或全部 0%argLine被覆盖agent 没注入find . -name *.exec报告只有单模块数据report和report-aggregate混用看target/site目录名报告缺了部分模块聚合模块没有声明对应依赖mvn dependency:tree覆盖率数字有但源码不显示source/class 路径解析失效或 reactor 不完整打开jacoco.xml搜sourcefile本地正常、CI 结果不一致插件版本不统一、构建时序拆分、skip 误配mvn help:effective-pom加-Dverbose7.2 让报告生成保持稳定的团队约定排查过这么多轮之后我现在的习惯是给团队立几条硬约定新增一个业务模块时必须同步把它加进聚合模块的dependencies。曾经我见过一个模块测试覆盖率接近 90%但因为忘了加依赖聚合报告连续两周都显示它是 0%。这事最坑的地方在于没人会主动发现因为它不报错。任何人在子模块里都不要单独执行mvn jacoco:report。统一由聚合模块的verify阶段产出报告。如果确实要单独看某个模块的覆盖率可以用 IDE 的 JaCoCo 插件而不是去手动触发 Maven 目标。CI 流水线里固定执行mvn clean verify不要拆开。拆开跑测试再跑报告短期看能省时间长期就是给自己埋坑。版本升级时先升父 POM 的pluginManagement再跑一次全量验证不要只在某个子模块里手动改版本。我在实际项目里还发现一个小技巧值得分享给聚合报告做成 CI 产物存档并在流水线脚本里加一个简单检查——如果jacoco-aggregate目录不存在直接让流水线失败。这些看起来多余的检查恰恰能在问题发生第一天就暴露出来而不是等到发布前才发现覆盖率一直不对。毕竟覆盖率报告的存在价值是让人信任它如果连聚合数据的完整性都没法保证那份报告反而不如不生成。