Python 虚拟环境与依赖管理：从混乱到可复现的工作流

很多 Python 项目的麻烦，并不是代码写错了，而是环境先乱了：A 项目要 requests 2.x，B 项目却依赖一个只认 1.x 的旧库；本地跑得好好的代码，换一台机器就装不上；半年后想复现一次演示，却怎么也凑不齐当时的依赖版本。把这些问题一次性讲清楚，就是虚拟环境与依赖管理的价值：它让每个项目拥有独立、可说明、可复现的运行环境。

为什么不要直接装进全局环境

全局安装看似省事，实际上把所有项目的依赖都混在同一个解释器里。版本冲突只是时间问题，更麻烦的是升级一个库可能悄悄影响另一个项目。虚拟环境把解释器、包目录和启动脚本隔离开，项目之间互不干扰，出了问题也只需要删掉重建，不会伤及系统 Python。

创建与激活虚拟环境

标准库自带的 venv 已经够用，不需要先装额外工具：

python -m venv .venv
source .venv/bin/activate

Windows 上则使用 .venv\Scripts\activate。激活后命令行提示符通常会出现 (.venv)，这就是当前环境已切换的标志。退出时用 deactivate 即可。建议把 .venv/ 写进 .gitignore，只提交代码和依赖清单，不提交环境本身。

一套可复现的依赖流程

推荐的工作顺序是：先激活环境，再安装依赖，最后把依赖落盘。安装时区分运行依赖和开发依赖，例如把测试、格式化工具放到单独的开发清单里，避免生产环境装一堆用不上的包。

pip install requests httpx
pip freeze > requirements.txt
pip install -r requirements.txt

pip freeze 的作用是把当前环境里实际装好的版本全部记录下来，新同事或新机器照单安装，就能尽量还原同一套组合。团队协作时，还可以在文档里写清最低 Python 版本、操作系统差异和需要系统库的包，避免只靠口头约定。

常见坑与处理办法

第一，忘记激活环境。这时安装的包进了全局环境，项目运行时却找不到。养成习惯：每次开终端先看提示符，必要时在项目说明里写明激活命令。

第二，版本写得太松或太死。完全不写版本，下次安装可能拿到不兼容的新版；全部精确锁定，又会让升级变得困难。折中做法是：对关键库给出兼容范围，对整体环境保留一份精确锁定文件，升级时逐个验证。

第三，只记包名，不记 Python 版本。有些库对 Python 版本有明确要求，换了大版本解释器仍然会失败。可以在项目配置里声明 requires-python，并在持续集成里用声明的版本跑一次测试。

第四，把虚拟环境当成备份。虚拟环境是可丢弃的，真正的资产是代码、配置和依赖清单。环境坏了不要修修补补，直接删除重建，往往更快也更干净。

给团队的检查清单

一个合格的 Python 项目，拿到新机器后应该能在几步内跑起来：创建虚拟环境、激活、按清单安装、运行测试。把这四步写进项目说明，并定期在干净环境里验证一次。如果某次升级导致测试失败，先回滚锁定文件，再单独升级可疑的包并记录原因，而不是同时改多个版本。

虚拟环境不是形式主义，而是把“在我机器上能跑”变成“在任何干净机器上都能跑”的关键一步。环境越清晰，排错就越快，协作成本也越低。