如何在CircleCI中缓存Python Poetry的安装？

要在CircleCI中缓存Poetry本身的安装（而非项目依赖），需针对Poetry的实际安装路径做精准配置，以下是可行的实现方案：

关键路径说明 #

Poetry通过官方脚本curl -sSL https://install.python-poetry.org | python3 -安装后，核心文件分布在两个关键目录：

• /home/circleci/.local/share/pypoetry：Poetry的完整安装目录，包含其自身的虚拟环境及核心执行文件
• /home/circleci/.local/bin/poetry：指向实际执行文件的软链接，用于全局调用Poetry命令

正确的CircleCI配置片段 #

- restore_cache:
    key: poetry-install-{{ checksum "poetry.lock" }}  # 若需固定Poetry版本，可替换为如poetry-install-1.8.3的固定字符串
    paths:
      - "/home/circleci/.local/share/pypoetry"
      - "/home/circleci/.local/bin/poetry"
- run:
    name: 安装或复用Poetry
    command: |
      # 检查缓存是否已恢复有效Poetry，未恢复则执行安装
      if ! command -v poetry &> /dev/null; then
        curl -sSL https://install.python-poetry.org | python3 -
      fi
      # 确保Poetry路径加入环境变量（缓存恢复后可能需手动生效）
      echo 'export PATH="/home/circleci/.local/bin:$PATH"' >> $BASH_ENV
      source $BASH_ENV
      # 验证安装状态
      poetry --version
- save_cache:
    key: poetry-install-{{ checksum "poetry.lock" }}
    paths:
      - "/home/circleci/.local/share/pypoetry"
      - "/home/circleci/.local/bin/poetry"

配置细节说明 #

1. 缓存键设计：用poetry.lock的校验和作为缓存键的一部分，确保项目依赖配置变更时能触发Poetry的重新安装；若需固定Poetry版本，可直接使用版本号作为缓存键的固定部分。
2. 缓存路径选择：必须同时包含Poetry的核心安装目录和软链接路径——之前仅缓存.cache/pypoetry的问题在于，该目录是Poetry的依赖缓存目录，而非Poetry自身的安装文件目录。
3. 安装前置判断：通过command -v poetry检查是否已存在有效安装，避免缓存恢复后重复执行安装脚本，大幅节省构建时间。
4. 环境变量配置：手动将Poetry的可执行路径加入PATH，避免缓存恢复后出现command not found的错误。

常见问题排查 #

• 缓存恢复后找不到Poetry：检查PATH是否包含/home/circleci/.local/bin，或验证软链接是否正确指向/home/circleci/.local/share/pypoetry/venv/bin/poetry。
• 缓存未生效：确认缓存键的唯一性，同时检查paths字段的目录路径与CircleCI执行环境中的实际路径一致（注意CircleCI默认使用circleci用户，而非root）。

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