自托管Windows GitHub Runner配置Python报安装错误如何解决

自托管Windows GitHub Runner执行Python项目工作流时，在actions/setup-python步骤抛出错误提示：Error happened during python installation，报错截图如下：

涉及的原始工作流配置如下：

name: Python application

on:
  push:
    branches: [ test ]
  pull_request:
    branches: [ test ]

permissions:
  contents: read

jobs:
  build:

    runs-on: test-excel

    strategy:
      matrix:
        python-version: [ "3.8", "3.9", "3.10" ]
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v3
        with:
          python-version: ${{ matrix.python-version }}

      - name: Create and start virtual environment
        run: |
          python -m venv venv
          source venv/bin/activate

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install openpyxl
          pip install -r requirements.txt
       
      - name: Run the app
        run: |
          streamlit run app.py

• actions/setup-python@v3版本对自托管Windows环境的兼容逻辑存在缺陷：默认会优先尝试从公网下载对应版本的Python安装包到runner工具缓存目录，不会主动识别系统已预装的Python，自托管环境如果存在公网访问限制、工具缓存目录权限不足的问题，就会直接抛出安装失败错误。
• 自托管runner的运行账号如果没有软件安装权限、runner目录下的_work\_tool缓存路径被设置为只读，会导致下载的Python安装包无法正常解压写入，触发安装报错。
• 现有工作流中的虚拟环境激活命令为Linux/macOS平台专属写法，在Windows环境下无法执行，该问题不会触发当前Python安装阶段的报错，但会导致后续依赖安装、应用运行步骤失败。

• 升级setup-python动作版本到v4及以上，该版本优化了自托管环境的Python识别逻辑，可自动读取系统已安装的对应Python版本，无需强制触发公网下载流程，修改对应步骤配置如下：

- name: Set up Python ${{ matrix.python-version }}
  uses: actions/setup-python@v4
  with:
    python-version: ${{ matrix.python-version }}

• 提前在自托管Windows runner主机上安装矩阵配置所需的3.8、3.9、3.10版本Python，安装时务必勾选Add Python to PATH选项，安装完成后重启runner服务，setup-python会自动匹配对应版本，跳过下载安装步骤。
• 检查runner服务的运行账号权限，确保runner根目录及下属所有子目录（尤其是工具缓存目录_work\_tool）拥有读写、执行权限，避免使用权限受限的系统内置账号运行runner服务。
• 修正Windows平台的虚拟环境激活逻辑，替换原Linux格式的命令为PowerShell兼容写法，避免后续步骤执行失败，修改后配置如下：

- name: Create and start virtual environment
  shell: powershell
  run: |
    python -m venv venv
    .\venv\Scripts\Activate.ps1

• 如果自托管runner无法直接访问GitHub公网资源，可在setup-python步骤中配置内部Python包镜像源，解决下载超时、连接失败的问题。

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