Python 环境管理：用 uv 跑通你的第一个项目

系列说明：这是「新生开发环境搭建」系列的第 2 篇。第 1 篇我们用 Scoop 装好了 uv 和基础工具，这一篇正式进入 Python 世界。没看第 1 篇的话，先回去把环境装好再回来。

一、Python 装上了吗？先搞清楚两件事

第 1 篇结束时，你应该已经执行过 scoop install uv。注意，装 uv 不等于装 Python——uv 是「管理工具」，Python 才是「运行环境」，就像装修公司和房子本身的关系。

先验证一下你机器上有没有 Python：

python --version

有输出（比如 Python 3.13.x）就直接往下看。提示「无法识别」也不用手忙脚乱，这正是 uv 的拿手好戏——它能替你下载和管理 Python，等会儿第五节就装上。

在动手之前，先建立一个贯穿全文的认知框架。初学者最容易混淆的就是「Python 的各种工具到底谁管谁」，一句话版本：

• Python 解释器：真正运行你代码的程序，一个机器上可以装很多个版本
• pip：Python 自带的「装包器」，往解释器里装第三方库
• 虚拟环境：每个项目独立的「包容器」，防止项目之间的库互相打架
• uv：上面三件事的统一管理者，一个工具全包了

🎓 讲师提示：这块概念表建议板书。学生之前若用过「Python 官网安装包 + pip」，讲清楚「为什么 uv 能取代那一套」是本节课的转折点。

二、为什么需要虚拟环境？一个血泪场景

想象期末小组作业：你们组的项目要用 requests 库的 2.28 版本，而室友拉着你在另一个项目里必须用最新的 2.34——同一个库，两个项目要的版本不一样。

如果所有库都装在系统 Python 里（pip 直装的默认行为），这两个项目就没法同时开发了，一升级全崩。更糟的是，等你这学期结束想清理电脑，根本分不清哪个库是哪个项目装的，删也不敢删。

虚拟环境（virtual environment）就是解药：每个项目拥有一个独立的、私有的库目录。项目 A 的 requests 2.28 和项目 B 的 2.34 各住各的屋，互不打扰；项目做完了，删掉它的环境目录，干干净净，系统 Python 始终是白纸一张。

「每个项目一个环境」是 Python 开发的铁律，从第一行代码就遵守它，你会省掉未来无数次调试环境的时间。

三、认识 uv：为什么选它而不是 pip

你的 Python 课本和大多数网上教程都会教 pip，那为什么我们直接上 uv？

uv 是 2024 年后快速崛起的新一代 Python 工具，用 Rust 写成，速度是 pip 的 10~100 倍。但比速度更重要的是它把散装的工具链收拢成了一个：以前你需要 pip（装包）+ virtualenv（建环境）+ pyenv（管 Python 版本）三个工具各司其职，现在 uv 一个全包，命令风格还高度统一。

学习成本几乎为零，还附赠两个大学期间立刻有用的能力：装包快（实验课现场等 pip 转圈的日子结束了）、环境可复现（队友 clone 你的项目后一条命令还原出和你一模一样的环境）。

四、第一站：用 uv 管理 Python 版本

uv 能直接下载和管理 Python 本身，这是它取代 pyenv 的能力。查看 uv 能找到哪些 Python：

uv python list

这个列表会显示两类东西：system 开头的是你机器上已装的，其余是 uv 可以帮你下载的。如果你想装一个指定版本的 Python（比如课上也要求用 3.12），一条命令：

uv python install 3.12

uv 会从国内可达的下载源把 Python 拉下来，放在自己的管理目录里，不会写注册表、不会碰系统设置，想删随时干净删除。上一系列课的意识在这里延续：所有东西都有统一的管理入口。

🎓 讲师提示：机房电脑大多预装了某个 Python，学生跑 uv python list 的输出会五花八门，正好借此讲解「system 与 managed 的区别」，比对着讲义念有效得多。

五、实战：从零跑通第一个项目

概念讲完了，现在建一个真正的项目。全程只需要五条命令。

第 1 步：建项目

cd 到你想放代码的目录（比如 D:\Code）
uv init hello-ml
cd hello-ml

uv init 会生成一个项目骨架：pyproject.toml（项目的「身份证」，记录项目叫什么、依赖哪些库）、.python-version（记录项目用哪个 Python 版本）、src 源码目录和一份 .gitignore。

第 2 步：加依赖

uv add requests

这一条命令背后发生了三件事：创建项目专属的虚拟环境（.venv 目录）、从镜像源下载 requests 及其依赖、把它们全部记录进 pyproject.toml 和 uv.lock。注意看输出——如果你之前 pip 装 numpy 要等半分钟，这里两秒内完成。

第 3 步：写代码

打开 src\hello_ml\__init__.py（或者新建 main.py），写上：

import requests

resp = requests.get("https://httpbin.org/get", timeout=10)
print("状态码:", resp.status_code)
print("你的第一个第三方库跑起来了！")

第 4 步：运行

uv run main.py

看到状态码 200，恭喜，完整链路走通了。

第 5 步（重点理解）：为什么用 uv run 而不是 python main.py？

uv run 会自动使用当前项目的虚拟环境来执行脚本。你不需要像老教程那样手动「激活环境」（.\.venv\Scripts\activate）——uv 在每次运行时自动搞定。忘了「激活环境」这个动作吧，uv run 就是新姿势。

🎓 讲师提示：第 5 步是本节最重要的概念点。学生迟早会在网上看到 activate 老教程，提前把「那是以往的手动方式，uv 会自动做」讲清楚，能防住未来的大量困惑。

六、换源：给 uv 配上国内镜像

第五步里 uv add 能飞快，有个前提——我们已经配好了国内镜像。uv 从 PyPI（Python 官方包仓库）下载包，而 PyPI 服务器在国外，不换源的话速度感人。

uv 通过环境变量配置镜像，在 PowerShell 里执行（复制粘贴时整段一起）：

[Environment]::SetEnvironmentVariable('UV_DEFAULT_INDEX', 'https://mirrors.aliyun.com/pypi/simple/', 'User')

这行命令把「默认包索引」设置为阿里云镜像，并且永久生效（写入了用户环境变量）。执行完重开一个 PowerShell 窗口，用 uv add 随便装个小包试试速度。

「永久生效」的另一面是：它写在系统环境变量里，不打开设置你平时看不到它。报错信息里出现的 URL 如果在项目文件里搜不到，第一反应就该去查环境变量——Get-ChildItem env: | Where-Object Name -match 'UV' 能列出所有 uv 相关的配置。这是排查包管理问题的一把万能钥匙。

常见的国内镜像还有腾讯云（https://mirrors.cloud.tencent.com/pypi/simple/）和中科大（https://mirrors.ustc.edu.cn/pypi/simple/），效果类似，任选其一即可。

🎓 讲师提示：实验室实测（2026-09）清华源曾对部分网络返回 403，故障排查课素材现成——「同一个镜像不同网络表现不同，所以排查思路比记住某个源更重要」。

七、协作场景：把项目交给队友

期末作业必然是小组协作。假设你把项目推到了 Gitee（下一篇讲怎么推），队友 clone 下来后，他的机器上怎么还原出和你一模一样的环境？答案简单到只有一条命令：

uv sync

uv 读取项目里的 uv.lock（锁定文件，精确记录了每个依赖的版本和下载地址），自动建环境、下载依赖，几分钟内队友的环境和你分毫不差。以前「我电脑上能跑啊」这种经典扯皮，从根上被消掉了。

反过来也成立：你自己换电脑、重装系统后，uv sync 一条命令恢复全部环境。uv.lock 要提交到 Git 仓库里，它是团队环境一致的守护者。

八、常见翻车现场与自救

uv add 报 403 Forbidden：镜像源故障或被限制。用第六节的方法换成其他镜像（腾讯云 / 中科大），重开终端再试。

python --version 和项目里的 Python 版本对不上：不用管。项目实际用哪个 Python 由 .python-version 和 uv 决定，uv run 时会自动选对；python --version 显示的只是系统里那个，两者可以并存。

装了包但 import 报错 ModuleNotFoundError：十有八九是你直接跑了 python main.py，绕过了虚拟环境。改用 uv run main.py。

队友说他那边装不上：让他确认执行过 uv sync，并检查 uv.lock 是否在仓库里（git status 看一眼，不在就补提交）。

想看项目里装了哪些包：uv tree 以依赖树的形式列出来，比 pip list 直观。

九、写在最后

回看这一篇的路径：虚拟环境解决「多项目打架」，uv 把环境、依赖、Python 版本收进一个工具，镜像源解决下载速度，uv.lock 解决团队一致性——四件事，环环相扣，都是为了让「代码能跑」这件事变得可预期。

Python 环境稳了，下一篇我们把代码托管的最后一环补上：Git 与 Gitee，让你的项目拥有完整的版本历史，也让队友能真正拿到你的代码。