本文旨在解决 GitHub 自托管 Runner 在配置 Python 环境时遇到的 "Version not found in local cache" 错误。通过分析问题原因，提供详细的解决方案，帮助开发者在非 Ubuntu/Windows 系统上成功配置 Python 环境，确保 CI/CD 流程顺利运行。本文重点在于理解 actions/setup-python 的限制，并提供替代方案。
问题分析
当在 GitHub 自托管 Runner 上使用 actions/setup-python action 时，可能会遇到如下错误：
Run actions/setup-python@v3 Version 3.9 was not found in the local cache Error: Version 3.9 with arch x64 not found The list of all available versions can be found here: `https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json`
该错误通常发生在自托管 Runner 的操作系统不是 GitHub Actions 官方支持的 Ubuntu 或 Windows 版本时。actions/setup-python action 依赖于预先构建好的 Python 发行版，这些发行版仅针对特定的操作系统环境提供。
解决方案
如果你的自托管 Runner 使用的是非 Ubuntu/Windows 的 Linux 发行版（例如 AlmaLinux、Fedora 等），直接使用 actions/setup-python action 可能会失败。以下是几种替代方案：
立即学习“Python免费学习笔记（深入）”；
1. 使用 Docker 容器
最推荐的解决方案是将你的构建过程封装到 Docker 容器中。Docker 容器提供了一个隔离且一致的环境，可以确保 Python 环境的正确配置，而无需依赖于主机操作系统的 Python 发行版。
步骤：
-
创建 Dockerfile： 在你的项目根目录下创建一个 Dockerfile，指定所需的 Python 版本和依赖。
FROM python:3.9 WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD ["python", "your_script.py"]
- FROM python:3.9：使用官方 Python 3.9 镜像作为基础镜像。
- WORKDIR /app：设置工作目录为 /app。
- COPY requirements.txt .：复制 requirements.txt 文件到容器中。
- RUN pip install --no-cache-dir -r requirements.txt：安装 requirements.txt 中列出的依赖。--no-cache-dir 选项可以减小镜像大小。
- COPY . .：复制项目所有文件到容器中。
- CMD ["python", "your_script.py"]：定义容器启动时执行的命令。
-
修改 GitHub Actions workflow 文件： 修改 .github/workflows/your_workflow.yml 文件，使用 Docker 容器执行构建任务。
name: Python application on: push: branches: [ "main" ] pull_request: branches: [ "main" ] permissions: contents: read jobs: build: runs-on: self-hosted steps: - uses: actions/checkout@v3 - name: Build and run Docker container run: | docker build -t my-app . docker run my-app- docker build -t my-app .：构建 Docker 镜像，并命名为 my-app。
- docker run my-app：运行 Docker 容器。
-
添加 .dockerignore 文件 (可选): 为了减小镜像大小并加速构建过程，可以创建一个 .dockerignore 文件，排除不必要的文件和目录。
.git __pycache__ *.pyc
2. 手动安装 Python
如果不想使用 Docker，也可以在自托管 Runner 上手动安装所需的 Python 版本，并在 workflow 文件中直接使用。
步骤：
-
安装 Python： 在自托管 Runner 上安装所需的 Python 版本。具体安装方法取决于你使用的 Linux 发行版。例如，在 AlmaLinux 上可以使用 dnf 命令：
sudo dnf install python39
-
修改 GitHub Actions workflow 文件： 修改 .github/workflows/your_workflow.yml 文件，直接使用已安装的 Python 版本。
name: Python application on: push: branches: [ "main" ] pull_request: branches: [ "main" ] permissions: contents: read jobs: build: runs-on: self-hosted steps: - uses: actions/checkout@v3 - name: Set up Python 3.9 run: | python3.9 -m pip install --upgrade pip pip install -r requirements.txt - name: Lint with flake8 run: | flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics - name: Test with pytest run: | pytest *.py- 移除 actions/setup-python@v3 action。
- 使用 python3.9 命令显式调用已安装的 Python 3.9 版本。
3. 使用 Conda (如果适用)
如果你的项目依赖于 Conda 环境，可以在自托管 Runner 上安装 Conda，并在 workflow 文件中使用 Conda 管理 Python 环境。
步骤：
安装 Conda： 在自托管 Runner 上安装 Miniconda 或 Anaconda。
-
修改 GitHub Actions workflow 文件： 修改 .github/workflows/your_workflow.yml 文件，使用 Conda 创建和激活环境。
name: Python application on: push: branches: [ "main" ] pull_request: branches: [ "main" ] permissions: contents: read jobs: build: runs-on: self-hosted steps: - uses: actions/checkout@v3 - name: Set up Conda run: | # Add conda to PATH export PATH="$HOME/miniconda3/bin:$PATH" conda env create -f environment.yml conda activate flow_corrections - name: Lint with flake8 run: | flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics - name: Test with pytest run: | pytest *.py- 确保 Conda 的可执行文件路径已添加到 PATH 环境变量中。
- 使用 conda env create -f environment.yml 命令创建 Conda 环境。
- 使用 conda activate flow_corrections 命令激活 Conda 环境。
注意事项
- 版本匹配： 确保在 Dockerfile 或手动安装时选择与项目兼容的 Python 版本。
- 依赖管理： 使用 requirements.txt 或 environment.yml 文件管理项目依赖，确保所有依赖项都已正确安装。
- 缓存： 可以使用 GitHub Actions 的缓存机制缓存 Docker 镜像或 Conda 环境，以加速构建过程。
- 安全： 在自托管 Runner 上安装软件时，请注意安全性，避免安装恶意软件。
- 清理： 定期清理自托管 Runner 上的 Docker 镜像和 Conda 环境，以释放磁盘空间。
总结
当在 GitHub 自托管 Runner 上遇到 actions/setup-python action 无法找到指定 Python 版本的问题时，通常是因为 Runner 的操作系统不受支持。通过使用 Docker 容器、手动安装 Python 或使用 Conda 等替代方案，可以成功配置 Python 环境，确保 CI/CD 流程顺利运行。选择哪种方案取决于项目的具体需求和 Runner 的配置。 使用 Docker 容器是推荐的做法，因为它提供了隔离性和一致性。
