进阶 1 · 环境与版本管理¶
第 10 章给了 uv/pip 的速览。本章深入：虚拟环境原理、多 Python 版本管理、两条工具链（uv / pip+venv）的完整工作流。Java 工程师习惯了"全局一个 JDK + Maven 管依赖"，Python 的环境管理是工程化的第一道坎——理解原理比记命令更重要。
1.1 为什么环境管理是 Python 的"第一关"¶
-
Java 的世界
-
Python 的世界
Java 把"依赖隔离"交给 Maven 的坐标体系；Python 把"依赖隔离"交给虚拟环境——每个项目一个独立的 site-packages。如果不隔离，A 项目要 django==3、B 项目要 django==5 就冲突，还会污染全局解释器。
两件事必须分开：① Python 解释器本身（哪个版本）② 第三方依赖（装在哪）。本章先讲 ①，第 2 章讲 ②。
1.2 虚拟环境原理¶
一个"虚拟环境"本质上是一个目录，里面有一份 Python 解释器的副本（或符号链接）+ 独立的 site-packages + 一个 pyvenv.cfg 标识文件。
.venv/
├── pyvenv.cfg # 标识：基于哪个全局 Python 创建
├── Scripts/ # Windows（macOS/Linux 是 bin/）
│ ├── python.exe # 解释器入口
│ └── activate # 激活脚本
└── Lib/site-packages/ # 这个环境独有的第三方包
激活的本质：把 .venv/Scripts（或 bin）插到 PATH 最前面，让 python/pip 指向虚拟环境里的那份。激活后命令行提示符出现 (.venv)。退出用 deactivate。
对照 JVM
Java 没有"虚拟环境"概念——因为 JVM 的依赖隔离在 Maven/Gradle 层（坐标 + 本地仓库）。Python 历史上把这事推给了"每个项目一份独立 site-packages"，于是有了 venv 这一层。uv 等现代工具正在把这个体验往 Maven 靠拢（一个命令管环境+依赖）。
1.3 路线一：uv 环境管理¶
uv 把"解释器版本 + 虚拟环境 + 依赖"统一管理，最接近 Maven/Gradle 的"一站式"。
多 Python 版本：uv python¶
uv 能自动下载和管理多个 Python 版本（不用 pyenv/手动装）：
uv python list # 列出可用版本（含已装 + 可下载）
uv python install 3.12 3.13 # 下载安装多个版本
uv python pin 3.13 # 给当前项目固定版本（写入 .python-version）
.python-version 文件记一个项目用哪个 Python 版本——团队成员/CI 读它自动用对的版本（类似 Java 项目声明 sourceCompatibility/targetCompatibility，但更直接）。
创建环境¶
uv init myproject # 新项目：生成 pyproject.toml + .python-version + .venv
cd myproject
# 或在已有项目里：
uv venv # 只建 .venv（用当前/pinned 的 Python）
uv venv --python 3.12 # 指定版本建环境
uv sync / uv add 会按需创建 .venv 并选对 Python 版本（uv init 只生成项目骨架）——你通常不需要手动 uv venv。
复现环境：uv sync¶
这是别人 clone 你的项目后第一条命令：读 uv.lock 装出完全一致的依赖版本。uv 极快（Rust 实现，比 pip 快 10–100 倍）。
运行¶
uv run 自动确保环境就绪再执行——很多团队根本不激活，全程 uv run xxx。
为什么主推 uv
一个工具搞定"解释器版本 + 虚拟环境 + 依赖锁定 + 运行"，且极快。心智模型最接近你熟悉的 Maven/Gradle。本仓库的两个贯穿项目（logstats、bookmarks-api）都用 uv。
1.4 路线二：pip + venv（传统，企业最常见）¶
标准库自带，无需额外安装。在没有 uv 的环境（受限网络、CI 基础镜像、老系统）仍是主流。
创建与激活¶
# 1. 创建虚拟环境（用当前 python）
python -m venv .venv
# 2. 激活（平台不同）
.venv\Scripts\activate # Windows CMD / PowerShell
source .venv/bin/activate # macOS / Linux
# 3. 用完退出
deactivate
⚠️ Windows 的两个坑
- 激活脚本是
.venv\Scripts\activate（不是 Unix 的bin/）。 - PowerShell 首次可能拒绝执行脚本，需一次性放宽：
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned。
多 Python 版本（pip 路线没有统一工具）¶
-
Windows：
pylauncher -
macOS/Linux：
pyenv
pip 路线的"多版本管理"要靠 py(Windows) / pyenv(Unix) 这类额外工具，而 uv 内建了——这是 uv 的显著优势之一。
装包¶
pip install requests # 装进激活的 .venv
pip install -r requirements.txt # 按清单装
pip freeze > requirements.txt # 冻结当前版本
⚠️ 最常见的坑
没激活 .venv 就 pip install → 装进了全局解释器，污染系统。养成习惯：先建/激活 .venv，再 pip。或干脆用 uv（默认就隔离）。
1.5 双路对照表¶
| 任务 | uv | pip + venv |
|---|---|---|
| 装 Python 版本 | uv python install 3.13 |
py -3.13 / pyenv install 3.13 |
| 固定项目版本 | uv python pin 3.13 |
手写 .python-version（pyenv 读） |
| 建虚拟环境 | uv venv（或自动） |
python -m venv .venv |
| 激活 | 通常不用（uv run） |
source .venv/bin/activate |
| 装依赖 | uv add / uv sync |
pip install / pip install -r |
| 复现 | uv sync（读 uv.lock） |
pip install -r requirements.txt |
| 锁文件 | uv.lock（自动、精确、含哈希） |
requirements.txt（手冻）或 pip-tools |
| 速度 | 极快（Rust） | 慢 |
1.6 选择建议¶
两者不冲突：同一项目可以同时有 .venv（被任一工具用）。本教程双路都讲透，你按环境选用。
本章练习¶
练习 1.1
用 uv 从零建一个项目 demo，固定 Python 3.13，说明 .python-version 文件的作用。
练习 1.2
解释为什么"没激活 .venv 就 pip install requests"是危险的，uv 如何避免这个问题。
参考答案
未激活时 pip install 装进全局解释器的 site-packages，污染系统、影响所有项目、难以卸净。uv 默认在项目 .venv 里操作（uv add/uv sync/uv run 都自动定位项目环境），从机制上避免了"装错地方"。
练习 1.3
pip 路线下，如何在 Windows 用 Python 3.12 创建一个虚拟环境？macOS 呢？
参考答案
Windows：py -3.12 -m venv .venv 然后 .venv\Scripts\activate。
macOS：python3.12 -m venv .venv（需已装 3.12）后 source .venv/bin/activate；或用 pyenv 装版本。对比：uv venv --python 3.12 一个命令跨平台搞定。
← 回首页 ｜ 下一章：进阶 2 · 依赖与包管理