在 Windows 上用官方 uv 搭建可复现的 Python 环境

许多教程在读者那一步就失败：作者机器上「正好装着某个 Python」，依赖没有锁定，命令也只写了一半。要把示例变成可复现的环境，需要两样东西：来源清楚的解释器，以及一份锁得住的依赖清单。本文在 Windows 上使用 Astral 的 uv 完成这件事，并始终以官方文档为安装依据。

为什么要单独谈环境

Python 本身并不难装，难的是「过几个月还能用同样的命令跑起来」。可复现的环境通常具备这些特征：

• 解释器版本被写下来，而不是口头说「最近的版本」。
• 依赖既有声明文件，也有锁定文件。
• 安装命令对项目目录有效，不依赖你在图形界面里手动勾选过的全局包。
• 清理方式明确，不会在系统里留下说不清来源的软件。

uv 把创建虚拟环境、安装依赖和锁定版本放在一组官方命令里，适合作为教程示例的默认工具。它不是唯一合法选择，但比「在全局环境里随便 pip install」容易讲清楚。

按官方方式安装 uv

打开 uv 的官方安装说明，使用文档为 Windows 提供的方法。常见做法是在官方页面复制安装命令，在 PowerShell 中执行。执行前请确认命令来自 docs.astral.sh 或 Astral 官方仓库，而不是转载页。

安装完成后，关闭并重新打开终端，然后检查：

uv --version

若命令无法识别，先确认文档中提到的安装位置是否已进入 Path，再重开终端。不要从随机网站下载名为 uv 的可执行文件。

创建一个可锁定的项目

在一个空目录中初始化项目（命令以你安装的 uv 版本的官方说明为准，以下为常见写法）：

mkdir hello-workshop
cd hello-workshop
uv init

成功后，目录里通常会出现 pyproject.toml 以及一个起始脚本。接着把你需要的库加进项目，例如只为演示而添加官方文档常用的请求库时：

uv add httpx

uv add 会更新声明文件并生成或刷新锁定文件（常见为 uv.lock）。把这两个文件一并纳入版本控制，读者才能安装到同一组版本。

指定 Python 版本时，按官方说明使用 uv python 相关命令，让 uv 从它所支持的官方来源获取解释器。把实际使用的版本号写进 README 和 .python-version（若工具生成了该文件）。

日常使用的几条命令

把下面几条写进项目 README，基本可以覆盖读者路径：

uv sync
uv run python main.py
uv lock
uv remove httpx

• uv sync 按锁定文件安装依赖，适合在另一台电脑上复现。
• uv run 在项目环境中运行命令，不必先手动激活环境（若你更喜欢激活，也可按文档使用虚拟环境脚本）。
• uv lock 在调整依赖后刷新锁定文件。
• uv remove 对称地删除不再需要的包。

运行测试或脚本时，同样通过 uv run 调用，避免误用系统全局的 Python。

不要这样做

• 不要下载所谓「已集成常用库」的非官方 Python 压缩包。
• 不要把虚拟环境目录提交进 Git。
• 不要在教程里只写 pip install 某包 而不给出版本或锁定文件。
• 不要为了「装得全」在示例项目中加入用不到的大型依赖。

如果你维护的是给读者看的仓库，请同时阅读《如何给教程配一个可复现的示例仓库结构》，把目录、许可和下载脚本一并补齐。

卸载与清理

不想继续使用某个项目时，删除该项目目录即可收回其虚拟环境（若环境建在项目内）。卸载 uv 本身时，按官方文档的说明移除可执行文件，并检查 Path 中是否还留有安装路径。系统级的官方 Python 如需卸载，使用 Windows「已安装的应用」中的官方条目。

一个写得清楚的环境，会让后面所有教程都变得容易复现。先把这一步做稳，再去跑模型或工作流，返工会少很多。