如何在GitHub Actions中缓存Poetry安装/虚拟环境以避免重复安装依赖？

我来帮你解决这个Poetry缓存的问题——你遇到的情况大概率是缓存路径配置错误，或者没让Poetry复用已缓存的虚拟环境。咱们一步步来搞定：

1. 先确定Poetry虚拟环境的实际路径 #

Poetry的虚拟环境位置不是固定的，取决于你的配置：

• 如果在pyproject.toml里设置了virtualenvs.in-project = true，虚拟环境会存在项目根目录的.venv文件夹中
• 默认情况下，它会存在系统缓存目录，比如Linux环境下是~/.cache/pypoetry/virtualenvs/

最靠谱的方式是在本地或者CI环境中运行poetry env info --path，这个命令的输出就是你需要缓存的准确路径。

2. 配置actions/cache的正确路径和缓存Key #

GitHub Actions的缓存核心是路径要精准，并且用唯一的Key来区分不同的依赖版本。这里给你一个经过验证的YAML配置示例：

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.9' # 替换成你项目使用的Python版本

      - name: Install Poetry
        run: |
          curl -sSL https://install.python-poetry.org | python3 -
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: 获取Poetry虚拟环境路径
        id: poetry-cache
        run: echo "::set-output name=dir::$(poetry env info --path)"

      - name: 缓存Poetry虚拟环境
        uses: actions/cache@v2
        with:
          path: ${{ steps.poetry-cache.outputs.dir }}
          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
          restore-keys: |
            ${{ runner.os }}-poetry-

      - name: 安装依赖（复用缓存）
        run: poetry install --no-root

几个关键细节： #

• 动态获取路径：用poetry env info --path自动获取路径，避免硬编码导致的错误（这很可能是你之前配置失败的核心原因）
• 缓存Key设计：把poetry.lock的哈希值加入Key，这样只有当依赖清单变更时，才会重新生成缓存，否则直接复用已有缓存
• restore-keys：设置前缀匹配规则，就算poetry.lock有小改动，也能复用之前的缓存，加快恢复速度

3. 确保Poetry使用缓存的虚拟环境 #

有时候缓存成功恢复，但Poetry可能会重新创建新环境。可以在缓存步骤后加一步，强制Poetry使用当前Python对应的虚拟环境：

- name: 激活缓存的虚拟环境
  run: poetry env use $(which python)

4. 验证缓存是否生效 #

最后可以加一步验证，确认依赖是否被正确加载：

- name: 检查已安装的包
  run: poetry run pip list

如果缓存命中，这里应该能看到你之前安装的pylint和pytest了。

为什么你的原有配置没生效？ #

从你描述的情况来看，大概率是缓存的路径不对——比如你可能硬编码了.venv路径，但实际上Poetry默认没把虚拟环境放在项目目录里，导致缓存的是空目录或者错误路径，自然恢复后找不到依赖。

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