GitHub Actions setup-python 项目中服务容器环境下缓存失效问题解析

问题背景

在使用 GitHub Actions 的 setup-python 动作时，用户报告了一个关于缓存机制的特殊问题：当工作流中同时存在普通任务和使用服务容器（service containers）的任务时，pip 包缓存在服务容器任务中未能按预期工作。

现象描述

用户配置了两个任务：

1. 普通任务 Job-A：成功使用了 pip 缓存
2. 带服务容器的任务 Job-B：虽然检测到缓存，但仍重新下载所有包

通过日志对比发现，Job-A 正确地从缓存中恢复了 pip 包，而 Job-B 虽然显示找到了缓存键，却仍然执行了完整的包下载安装过程。

技术分析

缓存机制原理

GitHub Actions 的 setup-python 动作通过以下步骤实现 pip 缓存：

1. 根据依赖文件（如 requirements.txt）生成唯一缓存键
2. 检查是否存在匹配的缓存
3. 如果找到缓存，则恢复 pip 包到本地缓存目录
4. 如果没有找到，则执行正常安装流程并创建新缓存

服务容器环境的影响

当任务中声明了服务容器时，GitHub Actions 会创建一个隔离的网络环境。这种隔离性可能导致：

1. 缓存路径解析差异
2. 环境变量传递问题
3. 文件系统访问权限变化

根本原因

问题的核心在于不同任务使用了不同的依赖文件：

• Job-A 使用 linter-requirements.txt
• Job-B 使用 requirements.txt 和 dev-requirements.txt

当没有明确指定缓存依赖路径时，setup-python 可能无法正确识别不同任务的依赖关系，导致缓存命中逻辑出现问题。

解决方案

明确指定缓存依赖路径

通过 cache-dependency-path 参数显式声明每个任务的依赖文件：

- uses: actions/setup-python@v5
  with:
    python-version: '3.10.10'
    cache: 'pip'
    cache-dependency-path: |
        backend/requirements/requirements.txt
        backend/requirements/dev-requirements.txt

最佳实践建议

1. 为每个任务单独配置缓存路径：确保不同任务的依赖文件被明确区分
2. 使用最新版本的动作：v5 版本包含更多缓存优化和错误修复
3. 清理旧缓存：在修改缓存配置前，建议清除历史缓存以避免冲突
4. 统一依赖管理：尽可能合并相似任务的依赖文件，减少缓存复杂度

环境差异说明

用户提到从 EKS 迁移到 EC2 后出现此问题，这可能是由于：

1. 不同运行器类型的文件系统实现差异
2. 缓存目录的默认位置不同
3. 环境初始化过程的细微差别

总结

GitHub Actions 的缓存机制在复杂环境下（特别是涉及服务容器时）需要更精确的配置。通过明确指定 cache-dependency-path 参数，可以确保缓存系统正确识别和处理不同任务的依赖关系，从而提高构建效率并减少不必要的包下载。

对于使用服务容器的 Python 项目，建议在 setup-python 动作中始终显式声明缓存依赖路径，这是保证缓存可靠性的最佳实践。