GitLab CI缓存yarn的node_modules频繁遇报错求助

问题根源 #

这个错误是Yarn找不到依赖状态文件导致的——你只缓存了node_modules，但Yarn还需要自身的状态文件（比如Yarn 1的.yarn-state.yml，Yarn 2+的.yarn/cache、.install-state.gz）来确认依赖是否正确安装。另外GitLab CI缓存偶尔命中失败、不同Job用了不同Yarn版本，也会触发这个偶发问题。

具体修复方案 #

1. 补全缓存路径，包含Yarn状态文件 #

根据你的Yarn版本调整缓存配置：

• Yarn 1.x：

  cache:
    key:
      files:
        - yarn.lock
    paths:
      - node_modules/
      - .yarn-state.yml
  

• Yarn 2+/Berry：

  cache:
    key:
      files:
        - yarn.lock
        - .yarnrc.yml
    paths:
      - .yarn/cache/
      - .yarn/install-state.gz
      - node_modules/ # 只有当你用nodeLinker: node-modules时需要
  

  用yarn.lock作为缓存key的一部分，依赖变更时自动生成新缓存，避免旧缓存干扰。

2. 加个 fallback 逻辑，缓存失效自动重装 #

在install任务里加判断，只要状态文件或node_modules不存在，就自动执行yarn install，不用每次都依赖缓存：

install_deps:
  stage: setup
  script:
    - if [ ! -f .yarn-state.yml ] || [ ! -d node_modules ]; then yarn install --frozen-lockfile; fi
  cache:
    # 用上文的缓存配置

3. 统一所有Job的Yarn版本 #

不同Yarn版本生成的状态文件不兼容，把所有Job的Yarn版本固定：

default:
  image: node:18-alpine
  before_script:
    - yarn set version 1.22.19 # 换成你实际使用的版本

4. 优化缓存命中稳定性 #

• 保持cache:policy: pull-push默认配置，让install任务负责更新缓存，其他任务只拉取缓存
• 不要在多个任务里修改node_modules，防止缓存污染
• 共享runner环境下，给缓存key加项目前缀，避免和其他项目冲突：

  cache:
    key:
      files:
        - yarn.lock
      prefix: "${CI_PROJECT_PATH_SLUG}"
  

为啥Artifacts能解决但不建议用？ #

Artifacts是把整个目录打包传输，不会缺文件，但大的node_modules传输耗时远超缓存加载，完全违背了缓存省时间的初衷，完善缓存规则才是正确方向。

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