PythonLearn/02_python进阶/2_8_虚拟环境与依赖管理/README.md

第 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 等框架。

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

import package_name

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

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

假设有两个项目：

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

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

还可能遇到：

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

五、什么是虚拟环境

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

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

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

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

六、创建虚拟环境

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

先在 PowerShell 进入项目根目录：

cd D:\Code\Python

创建环境：

python -m venv .venv

逐段理解：

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

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

七、激活虚拟环境

PowerShell 中执行：

.\.venv\Scripts\Activate.ps1

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

(.venv)

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

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

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

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

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

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

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

九、确认正在使用哪个 Python

激活前后都可以执行：

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

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

还可以执行本课示例：

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

示例通过比较：

sys.prefix != sys.base_prefix

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

十、退出虚拟环境

激活后执行：

deactivate

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

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

十一、什么是 pip

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

本课推荐始终使用：

python -m pip 命令

而不是只写：

pip 命令

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

十二、查看依赖

查看 pip 版本和安装位置：

python -m pip --version

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

python -m pip list

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

python -m pip show 软件包名称

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

python -m pip check

十三、安装与卸载依赖

安装命令格式：

python -m pip install 软件包名称

安装指定版本：

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

卸载：

python -m pip uninstall 软件包名称

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

十四、什么是版本固定

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

some-package==1.2.3

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

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

十五、使用 requirements.txt

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

package-a==1.2.3
package-b==4.5.6

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

python -m pip install -r requirements.txt

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

python -m pip freeze > requirements.txt

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

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

十六、不要提交 .venv

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

应该提交的是：

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

不应该提交的是：

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

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

.venv/
venv/

十七、完整示例

示例文件：

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

它只读取并输出：

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

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

十八、运行方法

未激活虚拟环境时运行：

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

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

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

完成代码练习后运行：

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

十九、预期结果

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

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

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

二十、常见错误

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

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

20.2 把依赖安装到错误环境

安装前先执行：

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