Python 虚拟环境 venv 从创建到依赖锁定

很多 Python 项目的问题，并不是代码写错了，而是环境装错了。同一台机器上装了多个项目，一个项目要 Django 4，一个项目要 Django 5，全局安装很快就会互相打架。虚拟环境 venv 就是为了解决这个问题：它给每个项目一个独立的解释器和包目录，项目之间互不干扰，出了问题也可以删掉重建，而不影响系统 Python。

一、创建一个干净的环境

在项目根目录执行创建命令，习惯上把环境目录命名为 .venv，这样一眼就能看出它是自动生成的目录，不应提交到版本控制：

python3 -m venv .venv

创建完成后，.venv 里会有一份独立的 Python 解释器和 pip。不要把源码、配置文件和虚拟环境混在一起，也不要把 .venv 复制给别人使用，因为它里面可能包含绝对路径，换一台机器往往无法直接运行。

二、激活环境是关键一步

创建不等于使用，必须先激活。Linux 和 macOS 下执行：

source .venv/bin/activate

Windows 的 PowerShell 下执行：

.venv\Scripts\Activate.ps1

激活成功后，命令行提示符前面会出现 (.venv)。这一步最容易被忽略：如果没有激活，pip 就会把包装到全局环境，看起来安装成功，换一个终端运行又找不到包。每次打开新终端，都要先确认提示符，再安装或运行。

三、确认用的是哪个解释器

激活后先做一次验证，不要凭感觉判断。执行 python 和 pip 的路径查看命令，确认它们都指向当前项目的 .venv 目录：

which python
python -m pip --version

如果路径仍然指向系统目录，说明激活失败，先检查当前 Shell 类型和激活命令是否匹配。Windows 上如果提示脚本执行受限，通常是执行策略问题，应按公司电脑的安全规范处理，不要随意绕过安全策略。

四、安装依赖并及时锁定

环境确认无误后，再安装项目需要的包，并把版本固定下来：

python -m pip install --upgrade pip
python -m pip install requests flask
python -m pip freeze > requirements.txt

这里推荐用 python -m pip，而不是直接写 pip，因为它能明确绑定当前虚拟环境的解释器。requirements.txt 就是项目的依赖清单，新同事拿到项目后，只要创建并激活环境，再执行安装命令，就能得到基本一致的依赖组合。

五、冻结依赖时要注意的坑

pip freeze 会列出当前环境里所有已安装的包，包括间接依赖。它的优点是完整，缺点是容易带上调试时临时装的包。提交前最好检查一遍清单，删掉与项目无关的包，或者把依赖分成两份：一份是运行必需的 requirements.txt，另一份是开发工具专用的 requirements-dev.txt。

另外，冻结文件里最好固定主版本号，避免下次安装时因为上游发布新版本而悄悄改变行为。如果项目已经上线，更要谨慎升级依赖：先在新环境里验证，再更新锁定文件，而不是直接在生产环境里升级。

六、团队协作的推荐流程

一个比较稳妥的协作流程是：克隆代码后创建虚拟环境，激活环境，安装锁定文件里的依赖，运行一次冒烟测试，确认通过后再开始开发。把 .venv、pycache 和本地配置文件写进 .gitignore，只提交代码和依赖清单。

当依赖发生变化时，改动代码的人要同时更新 requirements.txt，并在提交说明里写清楚新增或升级了哪个包、为什么需要它。这样 Review 的人不用猜，也方便出问题时快速回退到上一个锁定版本。

七、常见问题快速排查

如果激活后仍然找不到包，先看解释器路径，再看是否在正确的项目目录。如果提示模块缺失，可能是安装时没有激活环境，或者安装到了另一个环境。如果两个项目互相干扰，优先检查是不是共用了全局环境，而不是急着重装系统 Python。

环境彻底混乱时，最省事的办法往往是删除 .venv，重新创建并按锁定文件安装。这个操作成本很低，前提是依赖已经锁定好。反之，如果从来没有锁定依赖，重建环境就会变成一场猜谜游戏。

结语

虚拟环境的核心思想很简单：项目隔离、显式激活、及时锁定。养成这个习惯后，换机器、换同事、换部署环境都会轻松很多。先把 .venv 用好，再去研究更复杂的包管理工具，基础才不会塌。