Python 虚拟环境与依赖管理最佳实践

引言

在 Python 开发中，直接将第三方库安装在系统全局环境里是一种常见的反模式。这会导致项目间依赖版本冲突、环境污染等问题。本文将带你掌握标准的虚拟环境与依赖管理方案。

虚拟环境的核心实践

Python 自带的 venv 模块是创建隔离环境的官方标准工具。在项目根目录下执行以下命令即可创建名为 .venv 的虚拟环境：

python3 -m venv .venv

创建完成后，必须显式激活该环境：

# Linux / macOS
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

注意：在华为云 CodeArts 等 CI/CD 流水线中，建议直接调用 .venv/bin/pip 路径进行依赖安装，避免因未激活环境导致脚本执行异常。

依赖管理的演进与规范

传统的 requirements.txt 适用于中小型项目，但在生产环境中往往由于缺乏精确的版本锁定和依赖树管理而带来隐患。标准的实践流程如下：

1. 开发新功能时，安装并记录业务依赖：

pip install requests==2.31.0
pip freeze > requirements.txt

2. 在多环境部署时，建议使用更严谨的锁定机制。对于需要现代依赖解析的项目，推荐尝试 Poetry 或 pip-tools 来分离直接依赖与传递性依赖。

避坑指南与总结

新手常犯的错误是将 .venv 目录提交到 Git 仓库中。这不仅会导致仓库体积臃肿，还可能因为平台差异（如 C 扩展编译路径）引发崩溃。正确的做法是将 .venv/ 加入 .gitignore 文件，仅通过 requirements.txt 还原环境。

操作建议：请立即检查你当前的项目，确保所有服务部署脚本都在干净的虚拟环境中拉取依赖，并在代码库中严格维护锁定的版本清单。