# 第 2-8 课：虚拟环境与依赖管理

## 一、本课目标

完成本课后，你将能够：

1. 解释虚拟环境是什么，以及为什么需要它；
2. 在 Windows PowerShell 中创建、激活和退出虚拟环境；
3. 确认命令实际使用的是哪个 Python 解释器；
4. 使用 `python -m pip` 查看、安装和卸载第三方依赖；
5. 使用 `requirements.txt` 记录与恢复项目依赖；
6. 理解版本固定的基本作用；
7. 知道 `.venv` 不应提交到 Git。

## 二、前置知识

学习本课前，需要掌握：

- 在 PowerShell 中进入目录并运行 Python 文件；
- 模块与导入；
- 文件和路径；
- 基础异常处理；
- 类型注解。

## 三、什么是第三方依赖

Python 自带的模块组成标准库（Standard Library），例如 `pathlib`、`sys` 和 `platform`，使用它们通常不需要安装额外内容。

第三方依赖（Third-Party Dependency）是其他开发者发布、项目需要额外安装的软件包。例如以后 Web 阶段会使用 FastAPI、Django 等框架。

安装依赖后，我们可以在代码中导入它：

```python
import package_name
```

这里的 `package_name` 只是格式示例，不要求本课安装这个不存在的软件包。

## 四、为什么不能把所有依赖都装在同一个环境

假设有两个项目：

- 项目 A 需要某个软件包的旧版本；
- 项目 B 需要同一个软件包的新版本。

如果两个项目共用一个 Python 环境，升级项目 B 的依赖可能导致项目 A 无法运行。

还可能遇到：

- 不知道某个依赖属于哪个项目；
- 删除一个依赖时误伤其他项目；
- 自己的机器能运行，换一台机器却缺少依赖；
- 项目依赖越来越杂乱。

## 五、什么是虚拟环境

虚拟环境（Virtual Environment）是为一个项目准备的独立 Python 运行环境。它拥有自己的 Python 入口和依赖安装位置。

可以把它理解为每个项目自己的“工具箱”：

```text
项目 A → 自己的虚拟环境 → 自己的依赖
项目 B → 自己的虚拟环境 → 自己的依赖
```

虚拟环境不会复制整个操作系统，也不会删除系统 Python。它只是隔离 Python 解释器入口和软件包目录。

## 六、创建虚拟环境

本项目统一把虚拟环境放在项目根目录的 `.venv` 中。

先在 PowerShell 进入项目根目录：

```powershell
cd D:\Code\Python
```

创建环境：

```powershell
python -m venv .venv
```

逐段理解：

- `python`：使用当前 Python；
- `-m venv`：运行标准库中的 `venv` 模块；
- `.venv`：创建的环境目录名称。

创建可能需要几秒钟。成功后根目录会出现 `.venv`，但项目根目录的 `.gitignore` 已忽略它。

## 七、激活虚拟环境

PowerShell 中执行：

```powershell
.\.venv\Scripts\Activate.ps1
```

激活后，命令提示符前通常会出现：

```text
(.venv)
```

激活的作用主要是临时调整当前终端的命令查找顺序，让 `python` 和 `pip` 优先指向 `.venv`。

激活只影响当前终端窗口。关闭终端后，下次需要重新激活。

## 八、遇到 PowerShell 脚本限制怎么办

部分机器可能阻止运行 `Activate.ps1`。本课不要求为了激活环境而修改整台电脑的执行策略。

即使不激活，也可以直接使用虚拟环境中的 Python：

```powershell
.\.venv\Scripts\python.exe --version
.\.venv\Scripts\python.exe .\02_python进阶\2_8_虚拟环境与依赖管理\environment_example.py
```

这种写法目标明确，也能保证使用 `.venv`。如果遇到执行策略错误，保留英文错误原文，再说明你执行的命令，我会帮助判断。

## 九、确认正在使用哪个 Python

激活前后都可以执行：

```powershell
python -c "import sys; print(sys.executable)"
```

激活虚拟环境后，输出路径应指向项目中的 `.venv\Scripts\python.exe`。

还可以执行本课示例：

```powershell
python .\02_python进阶\2_8_虚拟环境与依赖管理\environment_example.py
```

示例通过比较：

```python
sys.prefix != sys.base_prefix
```

判断当前是否处于普通 `venv` 虚拟环境。

## 十、退出虚拟环境

激活后执行：

```powershell
deactivate
```

退出只会恢复当前终端的命令环境，不会删除 `.venv`。

以后重新使用时再次运行激活命令即可。

## 十一、什么是 `pip`

`pip` 是 Python 常用的软件包安装工具。它可以从软件包仓库下载和管理第三方依赖。

本课推荐始终使用：

```powershell
python -m pip 命令
```

而不是只写：

```powershell
pip 命令
```

`python -m pip` 能更明确地表示：“使用当前这个 Python 对应的 pip”，减少多个 Python 环境之间装错位置的风险。

## 十二、查看依赖

查看 pip 版本和安装位置：

```powershell
python -m pip --version
```

查看当前环境已安装的软件包：

```powershell
python -m pip list
```

查看某个已安装软件包的信息：

```powershell
python -m pip show 软件包名称
```

检查已安装依赖之间是否存在已知的不兼容：

```powershell
python -m pip check
```

## 十三、安装与卸载依赖

安装命令格式：

```powershell
python -m pip install 软件包名称
```

安装指定版本：

```powershell
python -m pip install 软件包名称==版本号
```

卸载：

```powershell
python -m pip uninstall 软件包名称
```

安装和卸载会修改当前 Python 环境。执行前必须先确认解释器路径，避免改动错误环境。本课不强制安装任何第三方依赖，也不要把示例中的占位名称原样执行。

## 十四、什么是版本固定

版本固定（Version Pinning）表示明确记录项目使用的依赖版本：

```text
some-package==1.2.3
```

它可以减少不同机器安装到不同版本而产生的差异。

需要注意：版本号必须来自项目实际验证过的环境，不要随意照抄教程中的旧版本。以后开始 FastAPI、Django 项目时，会根据实际环境选择并验证版本。

## 十五、使用 `requirements.txt`

`requirements.txt` 是常见的依赖清单文件，每行记录一个直接依赖或带版本的依赖：

```text
package-a==1.2.3
package-b==4.5.6
```

在另一台机器或新虚拟环境中恢复依赖：

```powershell
python -m pip install -r requirements.txt
```

根据当前环境导出所有已安装包：

```powershell
python -m pip freeze > requirements.txt
```

`pip freeze` 会记录当前环境中的全部软件包，包括间接依赖。导出前要确认环境干净、确实属于当前项目，避免把无关包写入清单。

本课没有第三方依赖，因此不会提前创建包含虚假依赖的 `requirements.txt`。

## 十六、不要提交 `.venv`

`.venv` 可能包含大量文件，并带有当前机器的路径和平台信息，不适合提交到 Git。

应该提交的是：

- Python 源代码；
- 课程文档；
- 经过确认的依赖清单。

不应该提交的是：

- `.venv/`；
- `__pycache__/`；
- 本地密钥和 `.env`。

本项目根目录 `.gitignore` 已包含：

```text
.venv/
venv/
```

## 十七、完整示例

示例文件：

```text
02_python进阶/2_8_虚拟环境与依赖管理/environment_example.py
```

它只读取并输出：

- Python 版本；
- 当前解释器路径；
- 当前环境目录名称；
- 是否为普通 `venv` 虚拟环境；
- 当前环境的 pip 版本。

示例不会创建环境，也不会安装或卸载依赖。

## 十八、运行方法

未激活虚拟环境时运行：

```powershell
python .\02_python进阶\2_8_虚拟环境与依赖管理\environment_example.py
```

创建环境后，不激活而直接运行：

```powershell
.\.venv\Scripts\python.exe .\02_python进阶\2_8_虚拟环境与依赖管理\environment_example.py
```

完成代码练习后运行：

```powershell
python .\02_python进阶\2_8_虚拟环境与依赖管理\practice.py
```

## 十九、预期结果

具体路径和版本因机器而异，格式类似：

```text
Python 版本：3.x.x
Python 解释器：某个实际路径
当前环境目录：某个环境名称
是否为 venv 虚拟环境：是或否
pip 版本：某个实际版本
```

在普通环境中通常显示“否”；使用 `.venv\Scripts\python.exe` 运行时应显示“是”。

## 二十、常见错误

### 20.1 创建环境后仍然使用原 Python

创建 `.venv` 不等于已经切换环境。需要激活，或者直接调用 `.venv\Scripts\python.exe`。

### 20.2 把依赖安装到错误环境

安装前先执行：

```powershell
python -c "import sys; print(sys.executable)"
```

确认路径后再使用 `python -m pip install`。

### 20.3 把 `.venv` 提交到 Git

虚拟环境是本地生成内容，应由 `.gitignore` 忽略。其他机器根据依赖清单重新创建。

### 20.4 把依赖清单当成虚拟环境

`requirements.txt` 只记录依赖名称和版本，不包含已安装文件。仍需先创建环境，再安装清单。

### 20.5 认为激活会永久改变系统

激活主要影响当前终端。执行 `deactivate` 或关闭终端即可退出。

### 20.6 随意修改 PowerShell 执行策略

激活脚本被阻止时，可以直接使用 `.venv\Scripts\python.exe`，本课不要求修改系统级策略。

## 二十一、课堂练习

练习分为两部分。

终端操作：

1. 在普通环境运行 `environment_example.py` 并记录结果；
2. 在项目根目录创建 `.venv`；
3. 激活环境，或直接使用 `.venv\Scripts\python.exe`；
4. 再次运行示例并比较解释器路径；
5. 执行 `python -m pip --version` 和 `python -m pip list`；
6. 退出环境并确认解释器恢复。

代码练习：打开 `practice.py`，完成环境判断、版本读取、环境报告和输出函数。

## 二十二、参考答案

参考答案暂不写入练习文件。完成后，我会验证函数行为和类型注解，并分别在当前解释器与临时虚拟环境中运行，确认环境判断能够反映真实差异。

## 二十三、本课小结

- 虚拟环境为项目隔离 Python 解释器入口和依赖；
- 使用 `python -m venv .venv` 创建环境；
- 激活后，当前终端优先使用虚拟环境；
- 不激活时也可以直接调用虚拟环境中的 Python；
- `python -m pip` 能减少把依赖装错环境的风险；
- `requirements.txt` 用于记录和恢复依赖；
- 版本固定有助于保持不同机器的环境一致；
- `.venv` 是本地生成目录，不应提交到 Git。

## 二十四、验收标准

- 能解释虚拟环境解决的问题；
- 能创建、进入和退出 `.venv`；
- 能确认当前 Python 解释器路径；
- 能使用 `python -m pip` 查看依赖；
- 能说明安装与卸载会修改当前环境；
- 能解释 `requirements.txt` 的用途；
- 能说明版本固定的基本作用；
- 能解释为什么 `.venv` 不应提交；
- 环境检查脚本在普通环境与 `.venv` 中显示不同判断；
- 没有把个人绝对路径或虚假依赖写入项目文件。