Github Actions缓存无法复用：如何创建通用缓存或移除分支限制？

你遇到的问题是因为actions/setup-python的默认缓存逻辑受分支隔离限制，PR分支无法复用主分支或其他分支的缓存，导致每次PR都重新生成缓存。以下是两种可行的解决方法：

方法一：手动配置通用缓存（推荐） #

放弃setup-python内置的cache参数，改用actions/cache手动定义缓存规则，让缓存键仅依赖于依赖文件的哈希值，与分支无关：

some-step:
  name: 'Test step'
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v3
    - run: pipx install poetry
    - name: Set up Python 3.8
      uses: actions/setup-python@v4
      with:
        python-version: "3.8"
        architecture: "x64"
        # 移除原有的cache: "poetry"配置
    - name: Cache Poetry dependencies
      uses: actions/cache@v3
      with:
        # 指定Poetry缓存的核心目录：虚拟环境和依赖缓存
        path: |
          ~/.cache/pypoetry/virtualenvs
          ~/.local/share/pypoetry
        # 缓存键由系统类型、Poetry标识和依赖文件哈希组成
        key: ${{ runner.os }}-poetry-${{ hashFiles('pyproject.toml', 'poetry.lock') }}
        # 降级匹配规则：如果找不到完全匹配的键，优先找同系统的Poetry缓存
        restore-keys: |
          ${{ runner.os }}-poetry-
    - name: Install dependencies
      run: poetry install
    - run: poetry run ...

关键说明： #

• path：指定Poetry存储虚拟环境和下载依赖的缓存目录，确保这些内容被缓存。
• key：用hashFiles生成pyproject.toml和poetry.lock的哈希值，只有当依赖文件变更时，缓存键才会更新，保证不同分支只要依赖一致就能复用缓存。
• restore-keys：当完全匹配的缓存不存在时，会尝试匹配前缀相同的缓存，进一步提升缓存命中率。

方法二：调整分支缓存访问策略（适用于保留setup-python内置缓存的场景） #

如果你想继续使用setup-python的cache参数，可以通过自定义缓存依赖路径，确保缓存键基于依赖文件哈希而非分支信息：

some-step:
  name: 'Test step'
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v3
    - run: pipx install poetry
    - name: Set up Python 3.8
      uses: actions/setup-python@v4
      with:
        python-version: "3.8"
        architecture: "x64"
        cache: "poetry"
        # 指定依赖文件路径，确保缓存键基于依赖文件哈希
        cache-dependency-path: "**/{pyproject.toml,poetry.lock}"

这种方式会让setup-python生成的缓存键包含依赖文件的哈希，而非分支信息。同时GitHub Actions默认允许PR读取其基础分支（如main/master）的缓存，只要PR的依赖文件与基础分支一致，就能命中缓存。

注意： #

如果你的PR基础分支不是主分支，手动配置缓存的方式灵活性更高，更推荐使用第一种方法。

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