如何在大型生产项目中使用uv进行环境打包-Python教程-PHP中文网

uv不是pip加速版，而是具备锁文件、跨平台预判和离线可重现能力的工程化打包方案；核心在于打得准、迁得稳、验得全，需严格遵循lock→compile→download流程并校验平台与Python小版本。

如何在大型生产项目中使用uv进行环境打包

uv 在大型生产项目中做环境打包，核心不是“装得快”，而是“打得准、迁得稳、验得全”。它不是 pip 的加速版，而是一套带锁文件 + 跨平台预判 + 离线可重现能力的工程化打包方案。

大型项目依赖树深、平台敏感组件多（如 pywin32、psycopg2-binary、CUDA 相关包），直接同步当前环境再打包，会埋下三类坑：

uv.lock 未生成或未更新：导致不同机器解析出不同版本，尤其在 CI 中用 uv add --upgrade 后忘记 uv lock
平台标识缺失：Linux 上 uv lock 默认按 Linux 解析，但目标可能是 Windows Server，pydantic 依赖的 typing-extensions 小版本可能不兼容
开发/生产依赖混用：没设 UV_NO_DEV=1，把 pytest、ruff 打进生产镜像，增大攻击面和体积

这是唯一能保证“开发机上打包，生产机上零网络还原”的路径：

先确保项目有 pyproject.toml，且所有依赖（含可选组）都声明清晰
运行 uv lock：生成精确的 uv.lock，含哈希、URL、平台约束
针对目标平台生成 requirements 清单：
uv pip compile pyproject.toml -o requirements-win.txt --platform win-amd64 --python-version 3.12
（Linux 目标则用 --platform manylinux2014_x86_64）
下载对应平台 wheel 包：
pip download -r requirements-win.txt --no-deps --only-binary=all -d ./wheels
⚠️ 注意：这里仍用 pip download，因为 uv download 当前（v0.7.x）不支持跨平台二进制包下载
最终打包目录结构应为：

Python uv 0.12.20
Python uv 0.12.20 是 Astral 开发的 Python 包与项目管理工具，支持依赖解析、虚拟环境、Python 版本及项目锁文件管理。本下载包适用于 Windows x64，解压后可使用 uv 命令。

下载
```
./dist/
├── wheels/          # 所有 .whl 文件（含依赖的依赖）
├── uv.lock          # 用于后续验证一致性
├── install.sh       # 内容：uv venv .env && uv pip install --find-links ./wheels --no-index -r requirements-win.txt
```

大型项目常有“开发用 3.12.3，生产要求 3.12.9”这类小版本硬性约束。仅靠 python-version 不够：

在 pyproject.toml 中显式写死：
[project.requires-python] = ">=3.12.9,
CI 中加校验步骤：
python -c "import sys; assert sys.version_info >= (3,12,9), 'Python too old'"
使用 uv python install 3.12.9 安装指定小版本（需提前配置 UV_PYTHON_INSTALL_DIR）
构建阶段禁用自动 Python 下载：设 UV_PYTHON_DOWNLOADS=0，强制使用预装 Python