如何用 uv 搭建一个快速、可复现的 Python 项目

当你让像 Claude Code 或 Codex 这样的 AI 编程智能体去处理一个 Python 项目时，一半的摩擦其实与模型毫无关系。它来自环境：缺失的包、错误的 Python 版本、智能体忘记激活的虚拟环境，或是某个"在我机器上能跑"的队友。解决之道是一个默认即可复现的项目，而如今实现这一点最快的方式就是 uv——这是来自 Astral、基于 Rust 的 Python 工具链。

uv 用一条快速的命令取代了 pip、venv、pip-tools 和 pyenv，并写出一个锁文件，从而在任何地方都能安装出完全相同的依赖树。本指南将带你在几分钟内从零开始，得到一个锁定且可运行的项目。

为什么环境对智能体很重要

AI 智能体在你的 shell 中运行命令，并读取返回的错误。如果你的项目没有声明任何依赖，也没有固定的 Python 版本，智能体就只能去猜——而一个错误的猜测会让它陷入歧途，比如把包安装到全局环境，或编辑错误的解释器。一个带有 pyproject.toml 和 uv.lock 的项目为智能体提供了单一可信来源：它可以运行 uv sync，获得正确的包，然后继续干活。你把审查时间花在逻辑上，而不是环境考古上。

安装 uv

在 macOS 或 Linux 上：

curl -LsSf https://astral.sh/uv/install.sh | sh

在 Windows 上（PowerShell）：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

uv 是一个单一的、自包含的二进制文件，所以无需再配置任何东西。

用一条命令开始一个项目

uv init weather-cli
cd weather-cli

这会搭建出一个可用的项目：一个用于元数据和依赖的 pyproject.toml、一个 .python-version 文件、一个起始的 main.py、一个 README.md 和一个 .gitignore。你不需要手动创建或激活虚拟环境——一旦你需要，uv 就会为你管理一个 .venv。

添加依赖（以及为什么锁文件很重要）

uv add requests

这一步同时做了三件事：在 pyproject.toml 中记录 requests、解析完整的依赖树，并将精确的、跨平台固定的版本写入 uv.lock。你也可以在添加时就固定版本：

uv add 'requests==2.31.0'

把 uv.lock 提交到 Git。它正是"安装最新的 requests"（会随时间漂移）和"安装我们测试过的那棵确切依赖树"之间的区别。当你的智能体——或你的 CI，或一位新队友——运行 uv sync 时，他们得到的是一个逐字节完全相同的环境。

无需激活任何东西即可运行代码

uv run main.py

uv run 会确保环境处于同步状态，然后在其中执行——无需 source .venv/bin/activate 这套繁琐操作。这对智能体尤其重要：每次工具调用往往是一个全新的 shell，所以"先激活再运行"经常会失败，而单独一条 uv run 总是有效。你可以包裹任何命令：

uv run -- pytest -q
uv run -- flask run -p 3000

固定 Python 版本，让智能体和 CI 保持一致

uv python pin 3.12

这会将版本写入 .python-version，uv 会自动下载并使用该解释器——无需系统 Python。这样一来，你开发时所用的版本，就是你的智能体、你的队友和你的 CI 全都使用的版本。

一个简短的实战示例

假设你让一个智能体"添加一个获取今天天气的命令"。有了 uv，整个循环都很干净：

uv init weather-cli && cd weather-cli
uv add requests
uv python pin 3.12
# 智能体编辑 main.py 来调用某个 API……
uv run main.py

智能体永远不必去推断哪个解释器处于激活状态，或者 requests 是否已安装——这些事实都声明在它可以读取的文件里。如果它引入了一个新依赖，它就运行 uv add，锁文件随之更新。如果 CI 中出了问题，uv sync 会在本地复现出那个确切的环境，让你可以调试它。

uv 的发展方向

uv 及其姊妹工具 ruff（代码检查器/格式化工具）和 ty（类型检查器）已被广泛采用——单是 uv 每月就有远超 1 亿次的下载量。2026 年 3 月，OpenAI 同意收购 Astral——它们背后的公司——以将该工具链并入其 Codex 平台，同时承诺将这些基于 MIT 许可证的工具保持开源（OpenAI、Simon Willison）。就目前而言，实际的要点没有改变：uv 是通往一个让你的 AI 智能体无需猜测即可构建的 Python 项目的最快路径。

快速参考

任务	命令
创建一个项目	uv init <name>
添加一个依赖	uv add <package>
固定 Python 版本	uv python pin 3.12
运行代码	uv run <file or command>
复现环境	uv sync
更新锁文件	uv lock --upgrade-package <pkg>