在 github actions 中集成 python uv，核心做法是在工作流中使用 astral-sh/setup-uv@v3 官方 action 安装并配置 uv。该 action 会自动处理不同操作系统上的二进制下载与缓存，随后即可通过 uv run、uv sync 或 uv pip install 等命令替代传统的 pip 和 venv 操作，从而显著加速依赖解析与安装过程。
如何在工作流中初始化 uv 环境
要在 GitHub Actions 中初始化 uv 环境，必须在作业（job）的早期步骤中调用 setup-uv Action。这一步会下载 uv 二进制文件并将其加入系统 PATH，同时自动创建虚拟环境（如果项目中存在 uv.lock 或 pyproject.toml）。初始化完成后，后续步骤可以直接使用 uv 命令，无需手动管理 Python 版本或虚拟环境路径。
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v3
with:
version: "0.4.25"
enable-cache: true
cache-dependency-glob: "**/uv.lock"
- name: Sync dependencies
run: uv sync --all-extras
- name: Run tests
run: uv run pytest
上述工作流首先检出代码，接着使用 astral-sh/setup-uv@v3 安装指定版本的 uv 并启用缓存。缓存键基于 uv.lock 文件生成，确保依赖变更时重新安装，否则复用本地缓存。最后一步通过 uv sync 同步所有依赖，并使用 uv run 执行测试命令。这种方式比传统 pip install 更快，因为 uv 使用了并行下载和更高效的锁定算法。
如何处理多版本 Python 测试
当需要对多个 Python 版本进行测试时，setup-uv Action 支持通过 python-version 参数指定目标版本。Action 会根据指定版本自动配置虚拟环境，并确保 uv 使用该特定版本的解释器。这使得在多版本矩阵测试中，无需额外配置 actions/setup-python，uv 能直接接管环境管理。
name: Multi-Python CI
on: [push]
jobs:
test:
strategy:
matrix:
python-version: ['3.9', '3.10', '3.11', '3.12']
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v3
with:
python-version: ${{ matrix.python-version }}
enable-cache: true
- run: uv sync
- run: uv run pytest
在此示例中，GitHub Actions 的矩阵策略定义了四个 Python 版本。每个矩阵实例都会触发一个独立的作业，setup-uv 根据 ${{ matrix.python-version }} 动态设置 Python 版本。这意味着 uv sync 会为每个版本安装对应的依赖，而 uv run 会使用相应版本的解释器运行测试。这种配置简化了多版本测试的流程，避免了手动切换 Python 环境的复杂性。
uv sync 在缓存命中时的具体行为
当 uv sync 执行且缓存命中时，它会跳过依赖解析和下载阶段，直接从缓存中恢复已安装的包。此时，uv 会验证当前项目依赖与缓存中锁定的依赖是否一致。如果一致，则直接链接或复制缓存中的包到虚拟环境，整个过程通常在毫秒级完成。若不一致，则仅更新变更的依赖，保持其余部分不变。
在实际运行中，如果 uv.lock 未发生变化，uv sync 的输出会显示类似 “Resolved X packages in Yms” 的信息，随后直接提示 “Installed Z packages”。这表明缓存机制生效，避免了重复的网络请求和计算开销。开发者可以通过检查日志中的时间戳来确认缓存是否被有效利用。此外，uv 的缓存是跨作业共享的，只要 uv.lock 不变，后续构建都能享受极速安装体验。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
