GitLab CI缓存失效问题排查：附.gitlab-ci.yml配置代码

首先明确：GitLab CI的全局缓存默认会自动应用到所有任务，不需要每个任务单独引用——但如果你的缓存没生效，大概率是配置细节出了问题，下面是常见原因和修复方案：

1. 缓存路径配置错误 #

检查你定义的缓存路径是否准确：

• Maven依赖的路径通常是~/.m2/repository（绝对路径，对应Runner用户的Maven仓库）
• Angular的node_modules是项目根目录下的相对路径，要确保写的是node_modules/（带斜杠避免匹配同名文件）
  如果路径写错，Runner找不到要缓存的文件，自然不会生效。

2. 缓存键（cache:key）设置不合理 #

这是最常见的问题：

• 如果三个环境的依赖完全一致，应该用基于依赖文件哈希的缓存键，比如把pom.xml和package-lock.json（或yarn.lock）加入键的生成依据，这样只有依赖文件变更时才会重新生成缓存，否则复用旧缓存：

  cache:
    key:
      files:
        - pom.xml
        - package-lock.json
    paths:
      - ~/.m2/repository
      - node_modules/
  

• 如果每个环境用了不同的键（比如分别设test-cache、pre-cache、prod-cache），会导致三个任务的缓存相互独立，无法共享，看起来像是缓存没生效。
• 别把动态值（比如时间戳、CI_JOB_ID）加入缓存键，否则每次任务都会生成新缓存，完全失去缓存意义。

3. Runner标签或执行环境不匹配 #

缓存是和Runner绑定的（默认存在Runner本地）：

• 如果三个任务用了不同标签的Runner，缓存无法跨Runner共享，每个Runner都会重新下载依赖。
• 如果你需要跨Runner共享缓存，得配置分布式缓存（比如用S3、Redis），但这属于进阶配置，先确认你的Runner是否一致。

4. 任务中意外禁用了缓存 #

检查每个任务的配置，如果某个任务写了cache: {}，会完全禁用该任务的缓存，导致依赖重新下载。

5. 验证缓存是否生效的小技巧 #

去GitLab CI任务日志里找Restoring cache和Saving cache这两行：

• 如果看不到这两行，说明缓存配置完全没生效
• 如果看到了，但依赖还是重新下载，大概率是缓存路径或键的问题

举个完整的正确配置示例：

# 全局缓存配置，所有任务自动复用
cache:
  key:
    files:
      - pom.xml
      - package-lock.json
  paths:
    - ~/.m2/repository
    - node_modules/

stages:
  - package_install

package_install_test:
  stage: package_install
  script:
    - mvn clean package -DskipTests
    - npm run build

package_install_pre:
  stage: package_install
  script:
    - mvn clean package -DskipTests
    - npm run build --configuration=pre

package_install_prod:
  stage: package_install
  script:
    - mvn clean package -DskipTests
    - npm run build --configuration=prod

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