如何解决 Jenkins CI/CD 构建时无法解析 Maven 依赖的问题

  技术百科     |      2026-01-25 00:00

本地构建成功但 jenkins 流水线失败，根本原因是 maven 在 jenkins 环境中优先使用 `settings.xml` 中配置的仓库地址（指向 `/repositories/wf-dependencies/`），而非 pom 中声明的 `/groups/dependencies/`，导致私有依赖无法命中。

在 Maven 构建过程中，仓库配置的优先级顺序为：settings.xml > pom.xml。即使你在 pom.xml 中正确定义了 指向 https://repository.workfusion.com/content/groups/dependencies/（该路径聚合了多个仓库，包含你所需的 rpa-custom-elements:1.4 和 idp-commons:2.0.6），Jenkins 所用的 Maven 实例仍会优先读取其全局或用户级 settings.xml（通常位于 Jenkins agent 的 $HOME/.m2/settings.xml 或 Jenkins 全局工具配置中指定的 settings 文件），而该文件很可能只配置了 wf-dependencies ID 对应的 /repositories/wf-dependencies/（单一仓库路径），该路径下并不包含所需构件。

? 验证与修复步骤如下：

  1. 确认 Jenkins 使用的 settings.xml 内容
    在 Jenkins Pipeline 中添加调试步骤，输出实际生效的 settings 文件路径及内容：

    sh 'mvn -X clean compile 2>&1 | grep "Reading global settings from\\|Reading user settings from"'

    或直接打印：

    sh 'cat $HOME/.m2/settings.xml'

  2. 统一仓库 URL：确保 settings.xml 中 wf-dependencies 的 与 POM 一致
    ✅ 正确配置（指向 groups）：

    
  
    
      workfusion-repo
      
        
          wf-dependencies
          https://repository.workfusion.com/content/groups/dependencies/
          true
          true
        
      
      
        
          wf-dependencies
       
       https://repository.workfusion.com/content/groups/dependencies/
            
          
        
      
  
    workfusion-repo

  3. （推荐）避免 POM 与 settings 冲突：将仓库声明移至 settings.xml，POM 中仅保留 ID 引用（不写 ）
    若需保持 POM 轻量化，可删除 pom.xml 中 块，仅依赖 settings.xml 统一管理——这是企业级 CI 最佳实践，确保环境一致性。

  4. 清理 Jenkins agent 缓存（关键！）
    旧构建可能已将错误仓库的元数据（如 resolver-status.properties）缓存在本地 .m2/repository/ 中，导致即使修复 settings 后仍尝试访问错误路径：

    sh 'rm -rf $HOME/.m2/repository/com/workfusion'
// 或彻底清理（谨慎）：
// sh 'rm -rf $HOME/.m2/repository/*'

✅ 最终验证方式：
在 Jenkins Pipeline 中执行带调试日志的构建：

sh 'mvn -U -e clean install'

观察日志中 Downloading from wf-dependencies: 后的 URL 是否为 .../groups/dependencies/...，并确认 rpa-custom-elements:1.4 成功下载。

⚠️ 注意事项： 不要同时在 pom.xml 和 settings.xml 中为同一 id 配置不同 ，Maven 会以 settings.xml 为准，且不合并路径； Nexus 的 groups 是虚拟仓库组（Group Repository），它聚合多个 hosted/proxy 仓库；而 repositories 下的是具体仓库实例，二者不可互换； Jenkins Maven 配置中若启用了“Use private Maven repository”，请检查其关联的 settings.xml 是否被覆盖。

通过统一仓库地址、清理本地元数据缓存，并将配置中心化到 settings.xml，即可彻底解决本地通而 Jenkins 失败的依赖解析问题。