GitLab CI Docker Runner的Maven仓库缓存失效问题排查

可能原因及对应解决方案 #

1. 缓存Key未合理配置，导致每次流水线重建缓存 #

GitLab CI默认缓存Key未关联依赖变更时，容易出现缓存不命中的情况。建议基于pom.xml的哈希值生成缓存Key，确保只有依赖定义变更时才更新缓存：

cache:
  paths:
    - .m2/repository/
  key: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG-$([[ -f pom.xml ]] && sha256sum pom.xml | cut -d' ' -f1)"

同时确认Runner节点：如果使用多节点Docker Runner，本地缓存无法跨节点共享，需配置分布式缓存（如S3、Redis）或固定使用同一Runner。

2. Maven配置强制全量更新依赖 #

检查$MAVEN_SETTINGS文件中的仓库更新策略，若releases节点的updatePolicy设为always，Maven会每次强制下载release依赖：

<repository>
  <id>infogreffe</id>
  <url>https://xxxx/nexus/repository/infogreffe</url>
  <releases>
    <!-- 改为never/daily，避免每次强制更新release依赖 -->
    <updatePolicy>never</updatePolicy>
  </releases>
  <snapshots>
    <updatePolicy>daily</updatePolicy>
  </snapshots>
</repository>

3. 缓存路径未正确加载或验证 #

在流水线脚本中添加验证步骤，确认缓存是否被正确恢复：

script:
  # 打印Maven仓库路径，确认配置生效
  echo "Maven local repo path: $CI_PROJECT_DIR/.m2/repository"
  # 检查缓存的依赖是否存在
  ls -la $CI_PROJECT_DIR/.m2/repository/org/wildfly/core/wildfly-core-security/19.0.0.Final/
  # 执行编译
  mvn --settings $MAVEN_SETTINGS clean compile

如果ls无输出，说明缓存未加载成功，需检查Runner的缓存配置（如config.toml中的[runners.cache]是否启用本地缓存）。

4. 避免缓存被意外清理 #

确认流水线中无其他步骤（如before_script）清理.m2目录，同时验证maven镜像不会覆盖你指定的仓库路径：通过MAVEN_OPTS设置的$CI_PROJECT_DIR/.m2/repository是正确的，避免和镜像默认的/root/.m2冲突。

5. 复用GitLab官方Maven模板（快速方案） #

GitLab提供了优化后的Maven流水线模板，内置正确的缓存策略，直接引用即可：

include:
  - template: Jobs/Maven.gitlab-ci.yml

variables:
  MAVEN_OPTS: >-
    -Dhttps.protocols=TLSv1.2
    -Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository
    -Dorg.slf4j.simpleLogger.showDateTime=true
    -Djava.awt.headless=true
  MAVEN_SETTINGS: your-settings-path.xml

build:
  tags:
    - tdev

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