解决actions/setup-node在自托管Runner上保存Yarn缓存的冲突问题

在GitHub Actions中使用自托管Runner执行构建任务时，开发人员可能会遇到Yarn缓存保存失败的问题。本文将深入分析这一问题的成因，并提供多种解决方案。

问题现象

当使用actions/setup-node@v4在自托管Runner上配置Node.js环境并启用Yarn缓存时，系统可能会报错："Cache already exists"。这表明有并发任务正在尝试创建或使用相同的缓存键。

问题根源分析

这种缓存冲突通常由以下两种情况引起：

1. 并发任务竞争：同一工作流中的多个任务或不同工作流中的任务同时尝试使用相同的缓存键
2. 缓存键重复：生成的缓存键唯一性不足，导致不同任务间产生冲突

解决方案

方案一：增强缓存键唯一性

通过向缓存键添加更多唯一性元素，可以有效避免冲突。推荐组合使用以下元素：

• 工作流运行ID(github.run_id)
• 操作系统类型
• 当前时间戳

- name: 创建唯一缓存键
  run: |
    echo "${{ github.run_id }}-${{ matrix.os }}-$(date +%s)" > .cache-key
- uses: actions/setup-node@v4
  with:
    node-version: 20.x
    cache: 'yarn'
    cache-dependency-path: |
      **/yarn.lock
      .cache-key

方案二：直接使用actions/cache

对于更精细的缓存控制，可以直接使用actions/cache来管理Yarn缓存：

- name: 缓存Yarn依赖
  id: cache-yarn
  uses: actions/cache@v4
  with:
    path: /Users/runner/Library/Caches/Yarn/v6
    key: yarn-cache-${{ runner.os }}-${{ matrix.os }}-${{ hashFiles('**/yarn.lock') }}
    restore-keys: |
      yarn-cache-${{ runner.os }}-${{ matrix.os }}-

最佳实践建议

1. 环境隔离：为不同的构建环境(如开发、测试、生产)使用不同的缓存前缀
2. 定期清理：设置定期任务清理过期缓存，避免存储空间浪费
3. 监控机制：添加缓存命中率监控，优化缓存策略
4. 文档记录：在团队内部记录缓存使用规范，确保一致性

通过实施这些解决方案和最佳实践，可以有效解决自托管Runner上的Yarn缓存冲突问题，提高构建效率和可靠性。