GitHubActions用Python3.14执行脚本怎么配

一、工作流文件创建与整体执行链路

GitHub Actions 会自动扫描仓库根路径下的 .github/workflows/ 目录。任何以 .yml 或 .yaml 结尾的文件都会被识别为自动化工作流任务。当设定的事件（例如代码推送到分支或手动点击触发）发生时，GitHub 就会在云端调起虚拟机执行定义的步骤。

运行 Python 脚本的整个链路非常清晰：虚拟机启动后，首先拉取项目代码，接着安装并配置指定的 Python 3.14 解释器，然后安装第三方库依赖，最后调用命令执行目标脚本。如下图所示：

图 1：GitHub Actions 从触发到运行 Python 3.14 脚本的五个核心环节

二、编写基础 Workflow 配置文件

在仓库内新建文件 .github/workflows/run-python-314.yml。以下是可以直接复制运行的标准配置示例：

# .github/workflows/run-python-314.yml
name: Execute Python 3.14 Script

on:
  push:
    branches: [ "main" ]
  workflow_dispatch: # 支持在 GitHub 网页上手动点击按钮触发

jobs:
  run-script:
    runs-on: ubuntu-latest

    steps:
      # 步骤 1：检出仓库代码到虚拟执行机
      - name: Checkout repository code
        uses: actions/checkout@v4

      # 步骤 2：配置 Python 3.14 环境
      - name: Set up Python 3.14
        uses: actions/setup-python@v5
        with:
          python-version: '3.14'
          cache: 'pip' # 启用 pip 依赖自动缓存加速

      # 步骤 3：验证 Python 与 pip 版本
      - name: Verify Python environment
        run: |
          python --version
          pip --version

      # 步骤 4：安装依赖清单
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi

      # 步骤 5：执行目标 Python 脚本
      - name: Run target script
        run: |
          python main.py

三、Python 3.14 版本的获取与解析机制

很多读者在刚配置时会疑惑：GitHub 官方虚拟机（Runner）是如何获取到 Python 3.14 的？

actions/setup-python@v5 内部封装了成熟的版本管理机制。当你的配置被触发时，Action 会首先检查虚拟机自带的本地工具缓存目录（Hosted Tool Cache）。如果 Runner 镜像中已经预编译并内置了该版本，只需秒级软链接即可投入使用。

若本地缓存未命中，Action 会自动请求 actions/python-versions 清单，根据当前 Runner 的操作系统与芯片架构（如 Linux x64、macOS arm64），下载对应预编译的 Python 归档包并完成解压和 PATH 注入。整个解析与落地过程如下：

图 2：setup-python 针对 Python 3.14 不同声明方式的解析与环境就绪架构

1. 预发阶段（Alpha / Beta / RC）的特殊配置

若 Python 3.14 处于预发布周期，或者 Runner 预装镜像尚未同步最新正式版标签，直接指定 '3.14' 可能会在日志中出现版本未找到的提示。此时只需在 with 下显式追加 prerelease: true 或直接指定预发快照标签：

      - name: Set up Python 3.14 (Prerelease support)
        uses: actions/setup-python@v5
        with:
          python-version: '3.14'
          prerelease: true
          check-latest: true

2. Python 3.14 自由线程版本（Free-threaded / 3.14t）

从 Python 3.13 与 3.14 开始，CPython 提供了实验性的无 GIL（全局解释器锁）自由线程构建。如果你需要测试无 GIL 下的多线程脚本执行表现，可以在 python-version 中直接加上 t 后缀：

      - name: Set up Python 3.14 Free-Threaded
        uses: actions/setup-python@v5
        with:
          python-version: '3.14t'

四、依赖缓存加速与脚本运行技巧

CI/CD 工作流往往会频繁触发。如果每次都从 PyPI 全量下载依赖包，不仅浪费时间，还会受到外部网络波动的干扰。通过在 setup-python 中配置 cache: 'pip'，GitHub Actions 会自动计算 requirements.txt（或 setup.py、pyproject.toml）的哈希值作为缓存 Key。

图 3：依赖缓存命中与脚本参数调用的时序交互机制

1. 传递执行参数与注入环境变量

当执行的 Python 脚本依赖外部参数或敏感机密（如 API 密钥、数据库连接串）时，严禁将凭据明文写在 YAML 文件中。推荐在 GitHub 仓库的 Settings -> Secrets and variables -> Actions 中录入 Secret，并在 Step 中通过 env 注入：

      - name: Run script with arguments and secrets
        env:
          API_TOKEN: ${{ secrets.API_TOKEN }}
          TARGET_ENV: "production"
        run: |
          python main.py --mode=batch --timeout=60

在 main.py 脚本内部，可以使用标准库 os.environ.get("API_TOKEN") 安全读取环境变量，实现配置与逻辑解耦。

五、跨版本矩阵配置（Matrix 策略）

如果你希望脚本既能在稳定的 Python 版本（如 3.12、3.13）上执行，同时又能前瞻性地验证在 Python 3.14 下的兼容性，可以使用 GitHub Actions 的 matrix 策略：

jobs:
  test-and-run:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        python-version: ['3.12', '3.13', '3.14']

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          prerelease: true
      - run: python main.py

开启 fail-fast: false 可以确保即便 3.14 遇到特定依赖兼容问题报错，也不会直接掐断其他 Python 版本的执行任务，便于分别排查。

六、运行结果验证与常见问题排查

提交并推送代码后，进入 GitHub 仓库页面，点击上方的 Actions 标签页即可查看当前正在运行或已完成的工作流。点击对应的任务节点，展开每一个 Step 可以查看标准输出日志。

图 4：全流程排障决策树与核心配置自查卡

七、总结

给 GitHub Actions 配置 Python 3.14 执行脚本，归纳起来就是“放对目录、用准 Action、写好单引号、管理好依赖”：

1. 工作流必须放置在 .github/workflows/*.yml。
2. 采用最新版 actions/setup-python@v5，并配置 python-version: '3.14'。
3. 善用 cache: 'pip' 加速安装，面对早期版本按需开启 prerelease: true 或无 GIL 的 '3.14t'。
4. 配合 python main.py 完成脚本调起，并借助 Actions 日志面板快速确认 Exit Code 与输出结果。