Python 虚拟环境与依赖管理：从 venv 到 requirements 的一次梳理

很多 Python 项目一开始跑得好好的，换一台电脑、换一个同事接手就出问题，十有八九不是代码写错了，而是环境没有管好。本文把我平时最常用的一套做法梳理一遍：用 venv 隔离环境，用 requirements 记录依赖，再留一个可复现的检查清单。

一、为什么需要虚拟环境

系统自带的 Python 往往还被其他工具共用，直接在全局安装包，很容易出现版本冲突：项目 A 要 requests 2.28，项目 B 要 2.32，装了新的就可能把旧的顶掉。虚拟环境就是给每个项目单独建一个小房间，解释器和第三方包都在房间里，互不干扰。出了问题删掉重建也不可惜，这比在全局环境里来回调试省事得多。

二、用 venv 建一个干净环境

Python 3 自带 venv，不用额外安装。习惯上把环境目录放在项目里或者项目外都可以，关键是不要把它提交到代码仓库。

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

在 Windows 上激活命令是 .venv\Scripts\activate。激活成功后，命令行前面一般会多一个 (.venv) 前缀，这就是最直观的确认方式。写脚本或者交接时，顺手把所用 Python 版本记下来，例如 python --version 的输出，避免别人用 3.9 跑 3.12 才支持的语法。

三、依赖要分层记录

很多人只留一个 requirements.txt，里面既有运行依赖又有调试工具，时间一长就分不清。我的做法是分两层：运行必须的放 requirements.txt，本地调试用的放 requirements-dev.txt，并在后者第一行引用前者。

pip freeze > requirements.txt

但要注意，pip freeze 会把所有已装包都列出来，包括间接依赖。提交前最好人工看一遍，删掉明显与项目无关的包，给直接依赖加上合理的版本范围，例如 requests>=2.31,<3，而不是把所有包都钉死在某一个小版本。这样既能复现，又不至于让后续升级寸步难行。

四、一个可复现的上手流程

新同事或者新电脑拿到项目后，理想流程应该只有四步：克隆代码、创建虚拟环境、安装依赖、跑一次冒烟测试。

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m pytest -q

如果这四步跑不通，优先检查三件事：第一，是否忘记激活环境；第二，是否用了系统 pip 而不是环境里的 pip；第三，是否有包需要系统级依赖，例如某些带 C 扩展的库在不同系统上表现不同。把这三点写进项目 README，比反复在群里问一句要高效。

五、常见坑与小习惯

第一，不要把 .venv 提交进 Git，一定要在 .gitignore 里加上它。第二，换电脑时不要直接复制虚拟环境目录，重新创建更稳妥，因为路径和系统库可能已经变了。第三，定期用 pip list --outdated 看一眼，但不要在生产环境临上线前盲目升级全部依赖，先在本地跑通测试再说。第四，项目里如果有多个入口脚本，尽量统一用 python -m 的方式运行，避免相对导入在不同目录下表现不一致。

结语

虚拟环境不是为了炫技，而是把“在我电脑上能跑”变成“在任何一台干净电脑上都能跑”。先隔离，再记录，最后留一份四步可复现的说明，这套习惯一旦养成，后续换环境、交接项目、排查依赖冲突都会轻松很多。