Python .venv 换电脑后失效：不要复制，用依赖定义重建

为什么压缩 .venv 通常会失败

虚拟环境基于创建它的基础 Python，内含解释器、脚本入口和指向本机路径的配置。Python 官方文档将 venv 定义为可丢弃、应易于重建、不进版本控制，且不应被视为可搬运或可复制。操作系统、CPU 架构、Python 小版本或项目绝对路径变化时，直接复制更容易留下隐性错误。

1. 旧机器只导出“定义和证据”

python --version
python -m pip --version
python -m pip freeze > requirements-observed.txt
python -m pip check

项目已经有 pyproject.toml、锁文件或人工维护的 requirements 时，它们才是主要依赖定义；pip freeze 只是当前安装状态的证据，不应不加审查地取代项目定义。同时记录系统、CPU、Python 版本与必要的外部库，不导出 Token 和密码。

2. 在目标位置新建环境

python -m venv .venv
# Windows PowerShell: ..venvScriptsActivate.ps1
# macOS/Linux: source .venv/bin/activate
python -m pip --version
python -m pip install -r requirements.txt
python -m pip check

如果项目使用 Poetry、uv、Pipenv 或 Conda，应使用该项目已经提交的配置与锁文件重建，不要混用多个管理器“补包”。

3. 遇到编译包不要强拷旧二进制

包含 C/C++/Rust 扩展的 Python 包可能与操作系统、架构和 Python ABI 绑定。安装失败时应保存完整错误、核对支持的 Python 版本和编译前置，不应把旧环境里的 site-packages 复制进新环境。

验收标准

1. sys.executable 指向新机器的项目 .venv。
2. python -m pip check 不报依赖冲突。
3. 核心测试和一条真实入口命令成功。
4. .venv 没有被 Git 跟踪，删除它后仍能根据已提交定义重建。

官方来源

• Python venv
• pip User Guide