# 代码在你电脑上能跑，uv 让它在客户机器上也能跑

> FDE 学 uv 不是为了快，而是为了在无法掌控的机器上重建同一套环境。

原文: https://fdetimes.net/zh/tools/uv-lockfile-reproducible-python-environments/

uv 的 README 列出了它想取代的工具：pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv，“以及更多”。在自己的 Mac、一家客户的 Linux 服务器和另一家客户的 Windows 机器上搭过同一条数据管道的 FDE，对这份清单不会陌生。清单上的每一个名字，都是环境可能出现差异的地方。

开发了 Ruff 的公司 Astral 把 uv 描述为一款用 Rust 编写、“极快”的 Python 包与项目管理工具。不过，速度并不是前线部署工程师（FDE）学习它的主要理由。主要理由是可复现性：你交付的代码，必须在你无法掌控、甚至从未见过的机器上表现一致。

如果你正准备转向 FDE 岗位，这项技能值得尽早练习，因为这份工作的核心就是交付在别人基础设施上运行的代码。在自己机器上跑通的演示说明不了多少问题，真正算数的是在客户机器上敲下的第一条命令能否成功。

## 问题通常不在代码里

设想一个常见场景。你在 Mac 上写了一个文档分类服务，充分测试后推送到 Git。客户那边的工程师把仓库克隆到一台 Windows 机器上，用机器上现有的 Python 版本安装依赖库，结果第一行就报了导入错误。

常见原因有三个：客户的 Python 版本和你的不同；依赖库在另一天解析，装上了不同的版本；或者你的锁文件只对生成它的操作系统有效。针对每一个原因，uv 都有明确的解法。

## 三个文件，一条命令

无论项目目前用的是 `requirements.txt` 还是其他工具，迁移到 uv 后的目标都是一个包含以下三项的仓库：

```
customer-project/
├── .python-version   # 提交
├── uv.lock           # 提交
└── .venv/            # 不要提交
```

`.python-version` 文件锁定项目的 Python 版本。`uv.lock` 文件记录需要安装的包，uv 文档特别强调它应当纳入版本控制。`.venv` 目录是每台机器上实际的环境，它不提交，因为任何机器都能根据锁文件重建它。

在客户机器上克隆仓库后，只需运行：

```
uv sync
```

uv 会读取 `.python-version`。如果机器上没有合适的 Python，uv 默认会下载一个，客户无需提前装好正确的版本。随后 uv 会严格按照 `uv.lock` 的记录构建 `.venv`。

关键词是“通用”（universal）。uv 生成锁文件时会针对所有平台做解析，因此同一份 `uv.lock` 可以跨操作系统使用。没有这种解析方式，锁文件只在生成它的平台上正确，上面场景中从 Mac 到 Windows 的失败正是这样发生的。

**要点:** 不要把环境搬到客户机器上，而是交付配方，让机器自己重建。

## 客户要求一模一样地复现上个月的结果

客户现场经常出现这样的需求：上个月的报告得出一个数字，现在重跑得出另一个数字，客户想知道原因。

如果锁文件和代码一起提交了，检出旧的提交就能解决大部分问题。如果必须从头解析，uv 提供了 `--exclude-newer` 选项，可以把解析范围限定在某个日期之前上传的发行包。

还有一种更小的情况：你为客户团队里的一位分析师匆忙写了一个数据清洗脚本。uv 允许按照 PEP 723 在脚本文件内部声明依赖，并单独锁定这个脚本。uv 文档指出，这样做的目的是让脚本日后再次运行时能重建同一套环境。

## 常见错误

第一个错误是提交 `.venv`。它体积大，与生成它的机器绑定，而且既然 `uv sync` 能根据锁文件重建环境，提交它完全多余。

相反的错误是认为 `uv.lock` 是生成文件，就不放进 Git。没有锁文件，客户机器会在另一天重新解析，你又会回到上面那个导入错误。

对于独立脚本，常见的错误是只声明依赖而不锁定。库的清单有了，但选中哪些版本取决于脚本运行的那一天。发送脚本之前，先锁定，再自己在一台干净的机器上跑一遍，确保客户拿到所需的一切。

## uv 帮不了你的地方

先说速度数据。官方文档称 uv 比 pip 快 10 到 100 倍，而 Charlie Marsh 在 2024 年 2 月 15 日的发布文章中称，在无缓存的情况下，uv 比 pip 和 pip-tools 快 8 到 10 倍。

两组数字对不上，所以哪一组都不能当作对客户基础设施的承诺。如果要谈速度，先在客户的机器上实测。

自动下载 Python 很方便，但要求客户机器能访问外网。在受严格管控的环境里，要在项目启动会上问清楚，并准备替代方案。此外，`uv.lock` 只记录 Python 包；驱动、系统库和机器配置都在锁文件之外，仍需单独检查。

## 先学什么

合理的顺序是：先学锁文件和 `uv sync`，再学 `.python-version`，最后才是 `--exclude-newer` 和内联依赖的脚本。最好的练习是自己动手弄坏再修好：删掉 `.venv`，换到另一种操作系统的机器上，检查一条命令是否足以让项目重新跑起来。

阅读 FDE 岗位描述时，留意“reproducible environments”（可复现环境）或“deploy on customer infrastructure”（在客户基础设施上部署）这类表述，这正是这项技能的用武之地。简历上不要只写“会用 uv”，而要写清楚你把环境搭建缩减到了几步，并举一个项目在陌生机器上顺利运行的具体例子。

客户不会记得你用了哪些工具。他们会记得的是，第一次克隆你的仓库时，一切是直接就能用，还是花了整整一个下午才修好。

**本周动手试试:**

- 挑一个旧项目，迁移到 uv 的结构，提交 uv.lock 和 .python-version，然后删掉 .venv，在另一种操作系统的机器上用 uv sync 重建。
- 写一个数据处理脚本，按照 PEP 723 在文件内声明依赖，用 uv 锁定，再请一位同事在他的机器上运行。
- 在简历上加一条具体的描述，例如“用 uv.lock 统一项目环境，新成员只需一次 uv sync 即可上手”。只有真正做到了再写。

## 信源

- [uv](https://docs.astral.sh/uv/)

- [uv: Python packaging in Rust](https://astral.sh/blog/uv)

- [GitHub - astral-sh/uv: An extremely fast Python package and project manager, written in Rust.](https://github.com/astral-sh/uv)

- [Structure and files | uv](https://docs.astral.sh/uv/concepts/projects/layout/)

- [Resolution | uv](https://docs.astral.sh/uv/concepts/resolution/)

- [Python versions | uv](https://docs.astral.sh/uv/concepts/python-versions/)

- [Running scripts | uv](https://docs.astral.sh/uv/guides/scripts/)
