Python 虚拟环境：从 venv 到依赖锁定的日常实践

很多 Python 项目的问题，并不是代码本身写错了，而是在不同的机器上跑出了不同的结果。同一份代码，在开发机上正常，在同事的电脑上却缺包、版本冲突，在服务器上又因为系统自带 Python 被改动而报错。虚拟环境要解决的，就是把项目运行环境和系统环境隔离开，让每个项目都有自己独立、可复现的依赖空间。

为什么需要虚拟环境

系统自带的 Python 往往被操作系统工具依赖，随意升级或安装包都可能影响系统组件。把项目依赖装进全局环境，还会让多个项目互相干扰：A 项目需要旧版框架，B 项目需要新版框架，全局只能保留一个版本。虚拟环境为每个项目创建独立的解释器和包目录，切换项目就切换环境，互不影响。调试时也可以放心删除重建，而不用担心破坏系统。

创建与激活

Python 3 自带 venv，不需要额外安装。习惯上在项目根目录创建名为 .venv 的目录，并把它加入版本控制忽略列表。创建命令是 python -m venv .venv。激活方式与系统有关，Linux 与 macOS 使用 source .venv/bin/activate，Windows 使用 .venv\Scripts\activate。激活后命令行提示符前会出现环境名称，这时再安装的包都会进入虚拟环境。退出时执行 deactivate 即可。

依赖管理的基本做法

进入虚拟环境后，先升级 pip，再按需安装依赖。开发过程中要养成随时记录依赖的习惯，而不是等到项目快上线才整理。可以用 pip freeze > requirements.txt 生成当前环境快照，但这个文件会包含所有已安装的包，包括间接依赖，阅读起来比较杂乱。更好的做法是把直接依赖写进 requirements.in 或 pyproject.toml，再用工具生成锁定文件，只在需要时更新。

锁定依赖与复现环境

锁定文件的意义，是把依赖版本固定下来，避免今天能跑、明天因为某个包发布新版就跑不起来。部署新机器时，先创建并激活虚拟环境，再用锁定文件安装，就能得到与开发时接近一致的依赖组合。升级依赖应当是有意识的操作：先在分支或新环境里验证，跑通测试后再更新锁定文件，并记录变更原因。不要在生产环境里直接执行无版本约束的安装。

常见坑与排查方法

最常见的坑是忘记激活环境，结果把包装进了全局环境，或者在虚拟环境里却用了系统 pip。排查时先看 which python 与 pip list，确认解释器路径是否指向项目下的 .venv。其次是把 .venv 提交进了代码仓库，既浪费空间又容易在不同系统上失效，正确做法是只提交依赖文件和配置。还有一种情况是项目路径移动后，虚拟环境里的绝对路径失效，最简单的办法就是删除旧环境、重新创建并安装锁定依赖。

一份可落地的检查清单

新建项目先创建虚拟环境，再安装依赖；提交代码时只提交依赖文件，不提交 .venv；换机器先复现环境，再运行测试；升级依赖先验证再锁定；遇到奇怪的导入错误，先检查当前解释器是不是项目环境。把这些步骤做成习惯，虚拟环境就不再是额外的负担，而是减少环境问题最划算的一步。