411 lines
11 KiB
Markdown
411 lines
11 KiB
Markdown
# 第 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` 中显示不同判断；
|
||
- 没有把个人绝对路径或虚假依赖写入项目文件。
|