Python venv 与 pip 镜像加速：把本地开发环境做干净、做快

刚开始学 Python 时，很多人会在系统自带的 Python 里直接 pip install，装得越多越乱：A 项目要 Django 4，B 项目要 Django 5，升级一个就可能把另一个跑坏；换一台电脑又要重新摸索装了什么。解决办法并不复杂，就是给每个项目一个独立的虚拟环境，再给 pip 配一个离自己更近的镜像源。下面这套做法，我在本地开发中一直在用，步骤少、出错也好排查。

一、为什么每个项目都要一个 venv

虚拟环境 venv 的核心作用是隔离。它会在项目目录里复制一份 Python 解释器和独立的 site-packages，项目依赖互不干扰，也不会污染系统 Python。好处很实在：第一，依赖版本可以按项目锁定，升级、回滚都有边界；第二，出了问题可以直接删掉 venv 重建，不用动系统环境；第三，配合 requirements.txt，别人拿到项目就能一键复现同样的依赖组合。需要提醒的是，venv 不是容器，它隔离的是 Python 包，不是操作系统层面的依赖，涉及系统库、数据库驱动时仍要看项目文档。

二、创建与激活：三条命令就够

在项目根目录执行：

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

创建成功后，终端提示符前面会出现 (.venv)，表示当前已进入虚拟环境。此后 pip install 的包都会装到 .venv/lib 下，而不是系统目录。退出用 deactivate，删除环境直接删 .venv 目录即可。习惯上把 .venv 写进 .gitignore，不要提交到代码仓库；团队协作时提交 requirements.txt，而不是整个虚拟环境目录。

Windows 下的激活命令不同，PowerShell 通常是 .venv\Scripts\Activate.ps1，如果执行策略拦截，需要先按提示调整策略或使用对应的批处理文件，不要绕过安全策略去改系统设置。

三、pip 镜像加速：只改配置，不改包名

国内直连默认源有时很慢甚至超时，这时换镜像源是最有效的办法。推荐用 pip config 写进用户级配置，而不是每次在命令后拼 -i 参数，这样所有项目都能受益。先在清华 PyPI 镜像站的帮助页找到它的 simple 地址，记为下面命令里的镜像地址：

pip config set global.index-url 镜像地址
pip config list

配置完成后，安装命令本身不需要改：

pip install requests httpx
pip install -r requirements.txt

如果只是临时测试某个源，可以用一次性的 -i 参数加同一个镜像地址，例如 pip install -i 镜像地址 requests，但不要把临时参数和正式配置混在一起，否则以后排查“为什么这台机器快、那台机器慢”会很费劲。公司内网有自建源时，同样用 index-url 或 extra-index-url 指向内网地址，并按内网文档处理证书与账号。

四、用 requirements.txt 锁定依赖

虚拟环境建好后，养成两个习惯。安装新包后及时导出，部署或换电脑时按文件安装：

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

pip freeze 会把间接依赖也列出来，版本很精确，适合复现；但如果要给别人看“项目真正依赖什么”，可以手写一份精简版，只列直接依赖并注明版本范围，例如 requests>=2.32。两种方式各有用途，复现用 freeze，阅读用精简版，不要只凭记忆装包。

五、常见坑与排查清单

第一，装包前先确认提示符里有 (.venv)，没有就说明还在系统环境里，装错地方要重新装。第二，不要用 sudo pip install，这会把包写进系统目录，和系统工具的依赖冲突后很难清理。第三，换源后仍很慢，先看是不是走了代理或 VPN，再用 pip config list 确认生效的 index-url，而不是反复换源碰运气。第四，报错提示找不到包或版本冲突时，先升级 pip 和 setuptools，再检查 Python 版本是否满足包的要求，很多“装不上”其实是版本下限问题。第五，虚拟环境损坏不要修修补补，直接删 .venv 重建，再按 requirements.txt 安装，往往比重装系统包更快。

六、一个干净的收尾流程

新建项目时按这个顺序走：创建目录、python3 -m venv .venv、激活、升级 pip、配置镜像源、安装依赖、导出 requirements.txt、把 .venv 加入 .gitignore。以后每次打开项目，先激活环境再工作，离开时 deactivate。环境干净了，调试时就少了很多“在我机器上能跑”的争论，换电脑、换同事交接也顺畅得多。把时间和精力留给业务逻辑，而不是反复折腾环境，这正是虚拟环境和镜像加速带来的最大收益。