GitLab CI/CD缓存过期致部署失败，求解决方案

问题背景 #

基于TypeScript的AWS CDK应用，配置了包含dependencies和deploy两个阶段的GitLab CI/CD流水线，原配置如下：

image: node:latest

stages:
  - dependencies
  - deploy

dependencies:
  stage: dependencies
  only:
    refs:
      - master
    changes:
      - package-lock.json
  script:
    - npm install
    - rm -rf node_modules/sharp
    - SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install --arch=x64 --platform=linux --libc=glibc sharp
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules
    policy: push

deploy:
  stage: deploy
  only:
    - master
  script:
    - npm run deploy
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules
    policy: pull

其中npm run deploy是CDK命令的封装。当流水线多周未运行时，GitLab默认30天的缓存过期，deploy阶段无法拉取缓存导致失败，报错：

Restoring cache
Checking cache for ***-protected...
WARNING: file does not exist                       
Failed to extract cache

问题根源 #

原dependencies阶段的only:changes规则仅在package-lock.json变更时才触发，当缓存过期但代码无变更时，该阶段不会运行，导致deploy阶段无法获取有效缓存。

解决方案 #

调整流水线配置，让dependencies阶段在master分支始终运行，但仅在缓存不存在时执行依赖安装，同时让deploy阶段依赖dependencies阶段，确保依赖总是可用：

image: node:latest

stages:
  - dependencies
  - deploy

dependencies:
  stage: dependencies
  rules:
    - if: $CI_COMMIT_BRANCH == "master"
  script:
    # 仅当node_modules不存在时才执行依赖安装
    - if [ ! -d "node_modules" ]; then
        npm install;
        rm -rf node_modules/sharp;
        SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install --arch=x64 --platform=linux --libc=glibc sharp;
      fi
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules
    policy: pull-push # 先尝试拉取缓存，成功则跳过安装，失败则安装后推送新缓存

deploy:
  stage: deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "master"
  needs: ["dependencies"] # 确保dependencies阶段完成后才执行deploy
  script:
    - npm run deploy
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules
    policy: pull

配置说明 #

• 触发规则调整：用rules替代旧的only语法，让dependencies阶段在master分支的所有流水线中都运行。
• 缓存策略优化：将dependencies阶段的缓存策略改为pull-push，先尝试拉取现有缓存，若成功则node_modules存在，跳过安装步骤；若缓存过期不存在，则执行安装并推送新缓存。
• 阶段依赖：deploy阶段通过needs依赖dependencies阶段，确保无论缓存是否存在，deploy执行前都已准备好有效依赖。

这样既实现了“尽可能跳过node_modules构建”的目标，又解决了缓存过期时流水线自动重建依赖的需求，避免部署失败。

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