团队统一使用 python uv 的核心做法是:在根目录创建 pyproject.toml 定义项目依赖,利用 uv sync 生成锁定文件 uv.lock,并通过 ci/cd 流水线或本地脚本强制同步环境。这样能确保所有开发者和构建服务器使用完全一致的包版本和平台二进制文件,消除 "在我机器上能跑" 的问题。

如何初始化项目并管理依赖
初始化项目时,使用 uv init 命令会自动生成标准的 pyproject.toml 和虚拟环境配置。开发者只需将 pyproject.toml 提交到版本控制系统,其他成员拉取代码后运行 uv sync 即可自动安装所有依赖并创建隔离的虚拟环境。这种方式替代了传统的 pip install -r requirements.txt 流程,且天然支持多平台预编译二进制包。

uv init my-project cd my-project uv add requests pytest uv sync
上述命令执行后,my-project 目录下会生成 pyproject.toml、uv.lock 以及 .venv 文件夹。uv.lock 记录了确切的依赖树和哈希值,保证环境可复现。
如何在 CI/CD 中集成 uv
在持续集成环境中,应直接使用 uv sync --frozen 命令来安装依赖。--frozen 标志会禁止更新 uv.lock 文件,如果锁文件与 pyproject.toml 不一致则报错,从而确保构建过程严格遵循已测试的版本组合。这比使用 pip 缓存或手动解析依赖要快得多,因为 uv 可以直接下载预编译的 wheel 包,跳过编译步骤。

# .github/workflows/ci.yml
- name: Setup Python and UV
uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Install UV
run: curl -LsSf https://astral.sh/uv/install.sh | sh
- name: Sync Dependencies
run: uv sync --frozen
该工作流首先安装 Python,然后安装 uv 工具,最后通过 uv sync --frozen 快速同步依赖。整个过程通常比传统 pip 安装快数倍,且无需配置复杂的缓存策略。
当 pyproject.toml 与 uv.lock 冲突时如何处理
当团队成员修改了 pyproject.toml 中的依赖但尚未运行 uv sync 时,uv.lock 就会过时。此时若直接运行 uv sync --frozen 会失败。正确的处理方式是先运行 uv sync(不带 --frozen),让 uv 重新计算依赖树并更新 uv.lock,然后将新的 uv.lock 提交到仓库。在 CI 中,如果检测到 uv.lock 需要更新,通常会报错并提示开发者本地同步后提交锁文件,以此维护依赖的一致性。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!











