Python虚拟环境venv与依赖锁定实战：从一台机器到可复现的运行环境

很多 Python 项目出问题，不是因为代码写错，而是因为运行环境变了：本地跑得好好的，换一台机器、换一个同事、过两个月再部署，依赖版本一变，报错就来了。虚拟环境 venv 加依赖锁定，就是把“这套代码在什么环境下能跑”写清楚、可复现的做法。本文用一个可直接照做的流程讲清楚。

一、为什么要隔离

系统自带的 Python 和全局 pip 环境会被多个项目共用。项目 A 要 requests 2.28，项目 B 要 requests 2.32，装在同一个环境里只能留一个版本，迟早互相干扰。venv 给每个项目一个独立的解释器副本和 site-packages，装包、升级、卸载都只影响当前项目，不动系统 Python，也不影响其他项目。原则很简单：一个项目一个环境，环境随项目走，不随机器走。

二、创建与激活

在项目根目录执行：

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

Windows 上激活命令是 .venv\Scripts\activate。激活后命令行提示符前会出现 (.venv)，此时 which python 和 pip 都指向虚拟环境内部。退出用 deactivate。建议把 .venv/ 写进 .gitignore，不要把整个虚拟环境提交进代码仓库——仓库里应该只有“如何重建环境”的说明，而不是环境本身。

三、依赖要分两层写

这是最容易做错的一步。直接把 pip freeze 的结果当作依赖清单交出去，虽然能复现，却把直接依赖和间接依赖混在一起，后续升级、排查都很痛苦。推荐分两层：

第一层是手工维护的 requirements.in 或直接写在文档里的直接依赖，只列项目真正 import 的包，并且给一个兼容范围，例如 requests>=2.31,<3、pydantic>=2,<3。范围太宽会漂移，钉死精确版本又会让升级困难，兼容范围是折中。

第二层是锁定的 requirements.txt，用 pip freeze 生成，记录每一次安装后实际落地的精确版本和间接依赖。这份文件才是部署和复现的依据。

工作流是：开发时按第一层装包，验证通过后立刻冻结成第二层并提交；部署和同事复现时只按第二层安装：

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

注意顺序：先装、再测、再冻结，不要在没跑通测试的情况下冻结一个坏环境。

四、复现检查清单

拿到一台新机器，按这个顺序验证：创建 venv 并激活；按锁定文件安装；运行一次最小可执行路径，例如启动服务或跑通核心单测；确认 pip list 里关键包的版本与锁定文件一致。如果报错，先看三点：是不是忘记激活导致装到了全局环境；是不是 Python 大版本不一致，例如本地 3.11、服务器 3.9；是不是系统级依赖缺失，例如某些包需要编译工具或系统库，这类问题锁定文件解决不了，要写进部署说明。

五、常见坑

第一，激活了环境却用绝对路径调用了系统 Python，例如定时任务、systemd、IDE 里配错了解释器路径，检查方法就是在运行环境里打印 sys.executable。第二，锁定文件里混入了开发工具，例如 pytest、black、ruff，这些应该放进单独的 requirements-dev.txt，生产部署不装。第三，只在本地冻结一次就再也不更新，依赖长期不升级会在某天集中爆发兼容问题，建议定期小步升级：一次只升一个直接依赖，跑测试，通过再重新冻结。

六、一个可落地的项目结构

myproject/
  .venv/                # 本地环境，不进仓库
  requirements.in       # 直接依赖，手工维护
  requirements.txt      # 锁定文件，部署依据
  requirements-dev.txt  # 开发工具
  README.md             # 写清创建、激活、安装三步

把这套流程固定下来，之后再遇到“在我机器上能跑”的问题，排查就有了起点：先对齐环境，再谈代码。环境可复现，问题才可复现；问题可复现，修复才可验证。