5.2 虚拟环境与依赖管理

5.2 虚拟环境与依赖管理

本节摘要：为什么永远不要往系统 Python 里装第三方包？因为依赖版本会打架，而且打起架来是全局范围。虚拟环境给每个项目一套独立的解释器入口与 site-packages。本节讲 venv 的原理与用法、pip 的进阶操作、pyproject 的依赖声明，给出一套可直接照抄的项目工作流。

从一场经典事故说起

场景你大概见过：项目 A 依赖某库 1.x，项目 B 依赖 2.x，都装在系统 Python 里。装 B 的那一刻，A 悄悄坏掉，直到某个深夜上线前才爆炸。这不是 pip 的 bug，是"全局共享一份 site-packages"的结构性缺陷。

解法是隔离：每个项目持有自己的环境目录，里面只放自己的依赖。先看原理——虚拟环境没有复制整个解释器，只是几份"指针"：

$ python -m venv .venv
$ ls .venv
pyvenv.cfg        # 声明：找上游哪个基础解释器、是否继承系统包
bin/ 或 Scripts/  # python 与 pip 的入口，指向基础解释器并绑定本环境
lib/site-packages/  # 本环境专属的第三方包安装地
​

激活只是把环境目录放到 PATH 最前，python 命中的就是它；退出用 deactivate。所以激活与否本质是"哪份 python 入口先被找到"——这也解释了为什么 IDE 里选对解释器比敲 activate 更重要：解释器选对了，不激活也一切正常。

虚拟环境分层

venv 工作流：可直接照抄

$ python -m venv .venv            # 建环境（进项目目录后）
# Windows: .venv\Scripts\activate    macOS/Linux: source .venv/bin/activate
$ python -m pip install --upgrade pip
$ python -m pip install requests pandas
$ python -m pip freeze > requirements.txt     # 锁定当前环境的精确版本
$ python -m pip install -r requirements.txt  # 别的机器一键复现
​

注意我全程写 python -m pip 而不是裸 pip——它保证 pip 装进"当前这条 python 命令"的环境，杜绝 5.1 节末尾说的"装错解释器"事故。团队协作时，.venv 目录加进版本库忽略清单（它可重建、体积大、还绑定绝对路径），提交的只有 requirements.txt。

依赖声明与版本约束

requirements.txt 是"快照"风格：记录当下装好的精确版本，复现力最强。现代项目则用 pyproject.toml 声明"意图"：

[project]
name = "myapp"
requires-python = ">=3.10"
dependencies = [
    "requests>=2.31,<3",
    "fastapi[all]~=0.110",
]

[project.optional-dependencies]
dev = ["pytest>=8", "ruff"]
​

约束符号速记：>=2.31,<3 半开区间最常用；~=0.110 等价于 >=0.110, <0.111（允许补丁级）；== 精确锁定（快照用）。可选依赖组让使用方按需安装——pip install "myapp[dev]" 装上测试工具，而生产环境不带。

两种文件的关系：pyproject 声明"我要什么"，锁定文件（requirements.txt 或由 pip-tools/uv 生成的 lock 文件）记录"最终装了什么"。前者给人和依赖解析器看，后者给部署机器看。

依赖地狱的三角与逃生

版本冲突的三角：上游动得快、传递依赖多、语义化版本不被严格遵守。诊断与逃生工具箱：

• pip list 看全景，pip show 库名 看某个包被谁依赖、装在哪；
• pip check 让 pip 自查已装集合是否有声明冲突；
• 冲突无解时，先问自己"真需要最新版吗"——降级到与队友一致的版本往往比重构依赖更快；
• 大型项目可考虑 pip-tools（编译 pyproject → 锁文件）或 uv（Rust 实现，装包快一个量级），思想相同、机制不变。

⚠️ 常见坑：忘激活环境就装包，装进了全局；把 .venv 提交进版本库；pip freeze 把无关包全锁进去（在干净环境里只装项目依赖再 freeze）；conda 环境与 venv 混用导致解释器来源混乱——数据科学生态用 conda 就全程 conda，别混。

💡 关键直觉：环境是"项目的一部分"，跟源码同级管理。判断题只有一个：python -c "import sys; print(sys.prefix)" 指向项目目录，就对了。

深挖：依赖解析为什么会打架

值得理解 pip 在背后做的事。装一个包时，pip 要解的是一道约束题：你声明的版本要求，加上这个包自己的依赖声明，再加上已装版本的约束，三方面必须同时满足。麻烦在于声明里常有开放区间（大于某个版本就行），解析器只能在安装时"贪心地"挑当时的最新版——于是今天装与下月装，结果可能不同，这就是"同一份 requirements 装出不同行为"的根源（也是锁文件存在的理由）。当约束无解时，pip 的报错会列出一长串版本冲突链，读法是从最后往前：最后那个"因为 A 要 X、B 要非 X"就是冲突核心。解法通常有三种：给其中一方手动钉一个双方都接受的中间版本；升级某一方让它放宽约束；或者接受现实——某些老旧组合确实无解，需要换库。理解了解析机制，"装不上"就从玄学变成了一道可推理的不等式题，团队里最稀缺的恰恰是能读这种报错的人。

本节要点回顾

• 结构性缺陷：全局共享 site-packages 必然版本打架；venv 用独立目录从结构上消灭冲突。
• venv 是指针不是拷贝：入口脚本 + pyvenv.cfg + 专属 site-packages，删除即卸载。
• python -m pip 铁律：永远与当前解释器对齐，杜绝装错环境。
• 两种依赖文件：pyproject 声明意图，requirements/lock 记录快照；.venv 不进版本库。
• 约束符号：>=,< 半开区间为主，~= 允许补丁级，== 锁定复现。
• 诊断工具箱：pip show / pip check / sys.prefix 三板斧。

至此，代码与环境的地基全部就位。下一章讲程序与外部世界的交互——文件读写与异常处理，以及它们背后统一的"协议"视角。