Jenkins构建Java8 Maven项目报错找不到maven:pom:3.1.0构件

DevOps 小满

2026-8-31

问题根因

核心触发点是Jenkins端Maven依赖解析异常，和项目pom本身无关：本地清空.m2目录仍能正常构建，说明依赖链路本身合法、私有仓库理论上存在对应构件，差异只出在Jenkins节点的环境配置上：
- 最常见原因是Jenkins全局settings.xml配置了mirrorOf=*的全局镜像，所有Maven仓库请求被强制转发到私有仓库，但私有仓库未正确代理Maven Central路径下org.apache.maven:maven:pom:3.1.0构件，或Jenkins使用的仓库账号无该路径读权限。
- 其次是Jenkins绑定的Maven版本和本地不一致：maven-surefire-plugin 3.0.0-M6对Maven核心版本有最低要求，如果Jenkins端Maven版本低于3.1.0，会触发异常的核心依赖拉取逻辑。
- 构建命令带-C（严格校验和校验）参数，如果私有仓库内的3.1.0版本pom文件损坏、校验和不匹配，Jenkins会直接判定拉取失败，本地如果未开启全局严格校验或曾缓存过正确文件就不会触发该问题。
- 少数情况是Jenkins节点网络策略限制：防火墙、出站代理规则拦截了对应构件路径的拉取请求，返回403、404或超时。
后续两个报错均为核心失败的衍生问题：
- Cucumber报告路径不存在是因为surefire插件初始化失败直接中断测试流程，根本没有执行用例生成报告。
- HTML文件解析不允许DOCTYPE声明是Jenkins默认HTML安全策略限制，属于次要配置问题，不影响核心构建流程。

排查&解决方案

先对齐Jenkins和本地的构建环境
- 登录Jenkins执行节点，运行mvn -v确认Maven版本、Java 8小版本和本地完全一致，不要使用Jenkins内置裁剪版Maven。
- 导出Jenkins节点使用的Maven配置文件（一般是Maven安装目录下的conf/settings.xml或Jenkins指定的全局配置文件），和本地.m2/settings.xml逐行比对
  、
  、
  节点：
  若存在mirrorOf=*的镜像规则，临时修改为mirrorOf=external:*，避免拦截Maven内置的核心构件请求，或确认私有仓库已正确代理Maven Central全量路径、Jenkins绑定的仓库账号有release仓库读权限。
  若配置了出站代理，确认代理规则未拦截私有仓库、Maven Central的请求。
定位具体依赖拉取失败原因
- 在构建步骤最前面临时加执行命令mvn dependency:resolve -X，开启debug日志重跑构建，看拉取org.apache.maven:maven:pom:3.1.0时的具体返回码：403是权限问题、404是私有仓库未同步对应构件、超时是网络拦截、checksum failed是文件损坏。
- 临时去掉构建命令的-C参数重跑，如果能正常拉取，直接去私有仓库删除org/apache/maven/maven/3.1.0路径下的所有缓存文件，触发私有仓库重新从上游同步正确构件即可。

兜底修复方案
如果上述配置调整后仍拉取失败，直接在pom.xml的surefire插件配置中显式声明对应核心依赖，跳过传递依赖解析：

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-surefire-plugin</artifactId>
      <version>3.0.0-M6</version>
      <dependencies>
        <dependency>
          <groupId>org.apache.maven</groupId>
          <artifactId>maven-artifact</artifactId>
          <version>3.1.0</version>
        </dependency>
      </dependencies>
    </plugin>
  </plugins>
</build>

衍生问题修复
- 核心依赖问题解决后，测试流程正常执行会自动生成Cucumber报告目录，无需额外配置。
- HTML解析DOCTYPE报错处理：进入Jenkins系统管理-全局安全配置，将Markup格式器从默认的纯文本改为安全HTML；如果使用HTML Publisher插件发布报告，在插件配置中关闭默认HTML消毒选项即可。

内容的提问来源于stack exchange，提问作者Thomarkey