JaCoCo是Java项目中应用非常广泛的代码覆盖率分析工具，常用于持续集成流程、单元测试质量评估以及代码质量管理。但在实际使用过程中，很多开发者会遇到这样的问题：执行JaCoCo覆盖率报告生成任务时，提示找不到.exec文件，导致报告生成失败。
典型错误信息如下：
Unable to read execution data file xxx/jacoco.exec
或者：
Skipping JaCoCo execution due to missing execution data file
这类问题通常不是报告插件本身异常，而是测试执行阶段没有正确生成覆盖率数据文件。本文将详细分析JaCoCo缺失.exec文件的原因，并提供针对性的解决方案。
JaCoCo .exec文件是什么
JaCoCo执行覆盖率统计时，会生成一个二进制数据文件，默认名称通常为：
jacoco.exec
该文件记录了测试运行期间：
-
哪些类被加载；
-
哪些代码分支被执行；
-
哪些方法被调用；
-
哪些代码行被覆盖。
后续生成HTML、XML或CSV格式覆盖率报告时，JaCoCo插件会读取这个.exec文件，然后分析测试覆盖情况。
完整流程如下：
代码编译 ↓ 执行单元测试 ↓ JaCoCo Agent收集数据 ↓ 生成 jacoco.exec ↓ 读取exec文件 ↓ 生成覆盖率报告
因此，如果.exec文件不存在，报告生成阶段自然无法继续。
常见原因一：没有绑定JaCoCo Agent
JaCoCo需要通过Java Agent方式插入测试运行过程，如果没有正确配置Agent，测试虽然可以执行，但不会产生覆盖率数据。
例如Maven项目中，如果只配置了：
XMLorg.jacoco jacoco-maven-plugin
并不会自动采集测试数据。
需要添加prepare-agent目标：
XMLorg.jacoco jacoco-maven-plugin 0.8.12 prepare-agent prepare-agent
该配置会自动生成测试运行参数：
-javaagent:jacocoagent.jar
让JaCoCo监听测试过程。
配置完成后重新执行：
Bashmvn clean test
通常可以看到：
target/jacoco.exec
文件生成。
常见原因二：跳过了测试执行
JaCoCo依赖测试过程采集数据，如果测试没有运行，就不会产生.exec文件。
例如：
Bashmvn package -DskipTests
或者：
Bashmvn install -Dmaven.test.skip=true
都会导致测试阶段被跳过。
解决方法：
执行完整测试流程：
Bashmvn clean test
然后生成报告：
Bashmvn jacoco:report
如果项目使用生命周期绑定，可以直接：
Bashmvn clean verify
常见原因三：Surefire插件配置导致Agent参数丢失
Maven项目中，JaCoCo通过argLine向Surefire传递Java Agent参数。
如果项目中手动配置了：
XMLorg.apache.maven.plugins maven-surefire-plugin -Xmx1024m
可能覆盖JaCoCo自动注入的参数。
正确方式：
XML${argLine} -Xmx1024m
或者：
XML${jacoco.argLine} -Xmx1024m
保证JaCoCo Agent参数不会丢失。
常见原因四：执行顺序错误
很多项目配置如下：
XMLreport report
但是没有执行测试数据采集。
正确执行顺序应该是：
-
prepare-agent
-
test
-
report
推荐配置：
XMLprepare-agent prepare-agent report test report
这样Maven生命周期会自动处理依赖关系。
常见原因五：多模块项目路径错误
在Spring Boot或大型Java项目中，经常采用Maven多模块结构。
例如：
project ├── pom.xml ├── module-a │ └── target/jacoco.exec └── module-b └── target/jacoco.exec
如果父工程执行：
Bashmvn jacoco:report
可能会寻找：
project/target/jacoco.exec
但实际文件位于：
module-a/target/jacoco.exec
解决方案：
在子模块执行：
Bashmvn clean test jacoco:report
或者使用：
XMLmodule-a module-b
并配置聚合报告：
XMLreport-aggregate
常见原因六：自定义exec文件路径不一致
JaCoCo默认路径：
target/jacoco.exec
如果修改过：
XML${project.build.directory}/custom.exec
那么生成报告时也必须保持一致：
XML${project.build.directory}/custom.exec
否则报告插件会读取错误的位置。
检查方式：
查看target目录：
Bashls target
确认实际生成文件名称。
Gradle项目缺失.exec文件解决方案
Gradle项目通常通过JaCoCo插件生成覆盖率数据。
开启插件：
gradleplugins { id 'jacoco' }
执行测试：
Bash./gradlew test
查看：
build/jacoco/test.exec
如果没有生成，可以检查：
gradlejacoco { toolVersion = "0.8.12" }
并确保测试任务启用：
gradletest { finalizedBy jacocoTestReport }
报告任务：
gradlejacocoTestReport { dependsOn test }
否则可能出现报告任务执行，但没有覆盖率数据的问题。
CI/CD环境中缺失exec文件排查方法
在Jenkins、GitLab CI、GitHub Actions等环境中，缺失.exec文件也非常常见。
建议按照以下顺序排查。
检查测试是否执行
查看构建日志：
Tests run: xxx
如果没有测试数量，说明测试阶段没有运行。
检查文件是否生成
增加：
Bashfind . -name "*.exec"
确认流水线环境是否存在：
jacoco.exec
检查构建缓存
部分CI系统缓存：
target/ build/
可能导致旧数据污染。
建议：
Bashmvn clean
或者删除：
target
重新构建。
检查权限问题
Linux环境下：
Bashls -l target/jacoco.exec
如果运行用户没有写权限，也可能无法生成文件。
修改权限：
Bashchmod -R 755 target
快速定位JaCoCo失败问题的方法
遇到.exec文件不存在时，可以按照以下检查清单：
1. 是否执行测试
确认：
Bashmvn test
是否成功。
2. 是否加载JaCoCo Agent
查看测试日志：
应该包含类似：
argLine set to -javaagent:...
3. 是否生成文件
检查：
Bashfind target -name jacoco.exec
4. 是否路径匹配
确认：
报告读取路径：
dataFile
和实际文件位置一致。
5. 是否被跳过
检查：
Bash-DskipTests
或：
Bash-Dmaven.test.skip=true
参数。
推荐的Maven完整配置示例
一个稳定的JaCoCo配置如下：
XMLorg.jacoco jacoco-maven-plugin 0.8.12 prepare-agent prepare-agent generate-report verify report
执行：
Bashmvn clean verify
即可完成：
-
编译；
-
测试；
-
生成exec文件；
-
输出覆盖率报告。
总结
JaCoCo覆盖率报告生成失败并提示缺失.exec文件，本质原因是覆盖率数据没有成功采集。最常见的问题包括：
-
未配置
prepare-agent； -
测试任务被跳过；
-
Surefire覆盖了JaCoCo参数；
-
多模块项目路径错误；
-
自定义exec文件路径不一致；
-
CI环境执行流程异常。
排查时应重点关注测试阶段是否运行、JaCoCo Agent是否加载、.exec文件是否生成以及报告读取路径是否正确。
正确配置JaCoCo后，通常通过：
Bashmvn clean verify
即可稳定生成覆盖率报告，为代码质量分析和持续集成提供可靠的数据支持。