Azure Pipeline中Maven本地仓库缓存失效问题求助

问题描述 #

在Azure Pipeline配置Maven本地仓库缓存时，缓存已成功加载且确认m2/repository文件夹存在，但执行Maven任务时仍会重新下载全部依赖，缓存完全失效。

最初使用的配置：

MAVEN_CACHE_FOLDER: $(Pipeline.Workspace)/.m2/repository

参考社区建议修改目录为$(HOME)/.m2/repository后问题依旧，当前完整配置如下：

pool:
  vmImage: ubuntu-latest

variables:
  MAVEN_CACHE_FOLDER: $(HOME)/.m2/repository
  MAVEN_OPTS: '-Dmaven.repo.local=$(MAVEN_CACHE_FOLDER)'

stages:
  - stage: validate
    displayName: VALIDATE
    jobs:
      - job: java_validations
        displayName: Java Validations
        workspace:
          clean: outputs
        steps:
          - checkout: self
            clean: false
          - task: Cache@2
            displayName: 'Cache Maven local repo'
            inputs:
              key: '"funcs" | maven | "$(Agent.OS)" | pom.xml'
              restoreKeys: |
              path: $(MAVEN_CACHE_FOLDER)
          - script: |
              mvn validate $(MAVEN_OPTS)
            displayName: Maven Validate
          - script: |
              mvn checkstyle:check $(MAVEN_OPTS)
            displayName: Maven Checkstyle
          - script: |
              tree $(MAVEN_CACHE_FOLDER)
            displayName: show MAVEN_CACHE_FOLDER tree
      - job: unit_tests
        displayName: Unit Tests
        dependsOn:
          - java_validations
        workspace:
          clean: outputs
        steps:
          - checkout: self
            clean: false
          - task: Cache@2
            displayName: 'Cache Maven local repo'
            inputs:
              key: '"funcs" | maven | "$(Agent.OS)" '
              restoreKeys: |
              path: $(MAVEN_CACHE_FOLDER)
          - script: |
              tree $(MAVEN_CACHE_FOLDER)
            displayName: show MAVEN_CACHE_FOLDER tree
          - task: Maven@3
            inputs:
              mavenPomFile: 'pom.xml'
              options: 'test-compile failsafe:integration-test -Dcheckstyle.skip -Pun-tests $(MAVEN_OPTS)'
              publishJUnitResults: false
              mavenVersionOption: 'Default'
              mavenAuthenticateFeed: true
              effectivePomSkip: false
              sonarQubeRunAnalysis: true
              sqMavenPluginVersionChoice: 'latest'
            env:
              JAVA_HOME: $(JAVA_HOME_17_X64)
              PATH: $(JAVA_HOME_17_X64)/bin:$(PATH)
          - script: |
              tree $(MAVEN_CACHE_FOLDER)
            displayName: show MAVEN_CACHE_FOLDER tree  

问题排查与修复步骤 #

1. 修正缓存Key配置 #

当前Cache@2任务的key存在多余转义引号，且restoreKeys为空，导致缓存匹配逻辑异常：

• 错误写法："funcs" | maven | "$(Agent.OS)" | pom.xml
• 正确写法：直接使用变量与文件哈希，无需转义引号

修改后的缓存任务配置：

- task: Cache@2
  displayName: 'Cache Maven local repo'
  inputs:
    key: 'maven | $(Agent.OS) | **/pom.xml'
    restoreKeys: |
       maven | $(Agent.OS)
    path: $(MAVEN_CACHE_FOLDER)

• **/pom.xml会计算所有pom文件的哈希值，确保依赖变更时缓存自动失效
• restoreKeys设置降级匹配规则，当当前key不匹配时，尝试加载同操作系统下的最新Maven缓存

2. 确保Maven任务正确读取仓库路径 #

虽然在options中传入了$(MAVEN_OPTS)，但可添加调试步骤验证参数是否生效：

- script: echo "MAVEN_OPTS=$(MAVEN_OPTS)"
  displayName: 打印MAVEN_OPTS参数

也可直接在Maven@3任务的mavenOptions字段中指定仓库路径，避免变量传递问题：

- task: Maven@3
  inputs:
    mavenPomFile: 'pom.xml'
    options: 'test-compile failsafe:integration-test -Dcheckstyle.skip -Pun-tests'
    mavenOptions: '-Dmaven.repo.local=$(MAVEN_CACHE_FOLDER)'
    # 其余配置保持不变

3. 统一多Job的缓存Key #

当前两个Job使用不同的缓存Key：java_validations包含pom.xml哈希，unit_tests未包含，导致第二个Job无法复用第一个Job生成的缓存。需统一两个Job的缓存Key配置。

4. 检查缓存路径权限 #

使用$(HOME)/.m2/repository时，需确认Pipeline Agent对该目录有读写权限，可添加检查步骤：

- script: |
    ls -ld $(MAVEN_CACHE_FOLDER)
    whoami
  displayName: 检查缓存目录权限

若权限不足，建议切换回$(Pipeline.Workspace)/.m2/repository，该目录属于Pipeline工作区，权限更可控。

5. 禁用快照依赖强制更新 #

若项目使用大量快照依赖，Maven会默认远程校验版本导致重新下载。可在MAVEN_OPTS中添加参数禁用快照更新（适合稳定构建场景）：

MAVEN_OPTS: '-Dmaven.repo.local=$(MAVEN_CACHE_FOLDER) -Dmaven.update.snapshots=false'

修复后的完整配置示例 #

pool:
  vmImage: ubuntu-latest

variables:
  MAVEN_CACHE_FOLDER: $(Pipeline.Workspace)/.m2/repository
  MAVEN_OPTS: '-Dmaven.repo.local=$(MAVEN_CACHE_FOLDER)'

stages:
  - stage: validate
    displayName: VALIDATE
    jobs:
      - job: java_validations
        displayName: Java Validations
        workspace:
          clean: outputs
        steps:
          - checkout: self
            clean: false
          - task: Cache@2
            displayName: 'Cache Maven local repo'
            inputs:
              key: 'maven | $(Agent.OS) | **/pom.xml'
              restoreKeys: |
                 maven | $(Agent.OS)
              path: $(MAVEN_CACHE_FOLDER)
          - script: echo "MAVEN_OPTS=$(MAVEN_OPTS)"
            displayName: 打印MAVEN_OPTS参数
          - script: |
              mvn validate $(MAVEN_OPTS)
            displayName: Maven Validate
          - script: |
              mvn checkstyle:check $(MAVEN_OPTS)
            displayName: Maven Checkstyle
          - script: |
              tree $(MAVEN_CACHE_FOLDER)
            displayName: 查看缓存目录结构
      - job: unit_tests
        displayName: Unit Tests
        dependsOn:
          - java_validations
        workspace:
          clean: outputs
        steps:
          - checkout: self
            clean: false
          - task: Cache@2
            displayName: 'Cache Maven local repo'
            inputs:
              key: 'maven | $(Agent.OS) | **/pom.xml'
              restoreKeys: |
                 maven | $(Agent.OS)
              path: $(MAVEN_CACHE_FOLDER)
          - script: echo "MAVEN_OPTS=$(MAVEN_OPTS)"
            displayName: 打印MAVEN_OPTS参数
          - script: |
              tree $(MAVEN_CACHE_FOLDER)
            displayName: 查看缓存目录结构
          - task: Maven@3
            inputs:
              mavenPomFile: 'pom.xml'
              options: 'test-compile failsafe:integration-test -Dcheckstyle.skip -Pun-tests'
              mavenOptions: '-Dmaven.repo.local=$(MAVEN_CACHE_FOLDER)'
              publishJUnitResults: false
              mavenVersionOption: 'Default'
              mavenAuthenticateFeed: true
              effectivePomSkip: false
              sonarQubeRunAnalysis: true
              sqMavenPluginVersionChoice: 'latest'
            env:
              JAVA_HOME: $(JAVA_HOME_17_X64)
              PATH: $(JAVA_HOME_17_X64)/bin:$(PATH)
          - script: |
              tree $(MAVEN_CACHE_FOLDER)
            displayName: 查看缓存目录结构

内容的提问来源于stack exchange，提问作者Diego Cândido da Silva