【Python基础】一文搞懂：Python 中 “requirements.txt“ 文件生成和使用

'# 【Python基础】一文搞懂：Python 中 “requirements.txt” 文件生成和使用

一、背景与问题

在 Python 项目开发中，依赖管理是核心问题之一。随着项目规模扩大，手动记录和维护依赖版本会变得低效且容易出错。requirements.txt 文件作为 Python 生态中最基础的依赖管理工具，其作用是明确项目所需的第三方库及其版本约束，确保在不同环境（如开发、测试、生产）中依赖版本的一致性。

然而，许多开发者对 requirements.txt 的原理、生成方式、使用场景以及潜在问题理解不深，导致在实际项目中出现依赖冲突、版本不一致、部署失败等问题。本文将深入解析 requirements.txt 的工作机制，结合真实开发场景，探讨其适用性与局限性。

二、基本原理

1. requirements.txt 的作用机制

requirements.txt 是一个纯文本文件，通过指定包名和版本约束来定义依赖关系。其核心原理是利用 pip 工具的依赖解析算法，确保安装时满足所有版本约束条件。

关键概念：

• 依赖解析（Dependency Resolution）：pip 根据 requirements.txt 中的依赖关系，按优先级和兼容性选择合适的版本。
• 版本约束（Version Constraints）：通过 ==、>=、<=、!= 等符号定义版本范围，例如 Flask==2.0.1 或 requests>=2.25.1。
• 虚拟环境（Virtual Environment）：requirements.txt 通常与虚拟环境配合使用，隔离不同项目的依赖。

2. pip 的依赖解析算法

pip 使用 greedy algorithm（贪婪算法）来解析依赖。其核心逻辑是：

1. 优先安装最新版本的包。
2. 如果依赖冲突，尝试降级依赖包以满足所有约束。
3. 若无法满足，抛出错误提示。

这种算法虽然高效，但也可能导致“依赖地狱”（Dependency Hell），例如多个包需要不同版本的依赖库。

三、环境准备

1. 前提条件

• 安装 Python（建议 3.8+）。
• 安装 pip（通常随 Python 一起安装）。
• 安装 wheel（用于生成 requirements.txt）。

2. 示例环境

# 创建虚拟环境
python -m venv env
source env/bin/activate  # Linux/Mac
env\Scripts\activate     # Windows

# 安装依赖
pip install wheel

四、核心实现

1. 手动编写 requirements.txt

最简单的 requirements.txt 文件格式如下：

Flask==2.0.1
requests>=2.25.1

关键代码解释：

• Flask==2.0.1：明确要求 Flask 的精确版本。
• requests>=2.25.1：允许安装 2.25.1 及以上版本。

常见错误：

• 错误示例：Flask!=2.0.1（使用 != 会引发版本冲突，导致无法安装）。
• 解决办法：使用 >=、<= 或 == 定义版本范围。

2. 使用 pip freeze 生成 requirements.txt

pip freeze 命令会列出当前环境中所有已安装包及其版本，适用于快速生成依赖文件。

pip freeze > requirements.txt

关键代码解释：

• pip freeze 会输出类似以下内容：

  Flask==2.0.1
  requests==2.25.1

• 该命令会包含所有依赖包，包括间接依赖（transitive dependencies）。

注意事项：

• 不推荐直接使用：pip freeze 生成的文件可能包含大量冗余依赖，导致部署时安装速度变慢。
• 建议精简：结合 pip freeze 和手动编辑，仅保留项目直接依赖。

3. 使用 pip install 安装依赖

通过 requirements.txt 安装依赖的命令如下：

pip install -r requirements.txt

关键代码解释：

• pip install 会根据 requirements.txt 中的版本约束安装对应包。
• 如果存在冲突，pip 会尝试降级依赖包，但可能无法完全解决。

常见错误：

• 错误示例：requirements.txt 中指定 Flask==2.0.1，但系统中已存在 Flask==2.1.0，导致冲突。
• 解决办法：使用 pip install --upgrade 更新依赖，或手动编辑 requirements.txt。

五、完整案例

案例：Flask 项目依赖管理

项目结构

my_project/
├── app/
│   └── __init__.py
├── requirements.txt
└── setup.py

1. 生成 requirements.txt

# 安装 Flask 和 requests
pip install Flask==2.0.1 requests>=2.25.1

# 生成 requirements.txt
pip freeze > requirements.txt

2. requirements.txt 内容

Flask==2.0.1
requests==2.25.1

3. 安装依赖

# 在另一台机器上安装
pip install -r requirements.txt

4. 安装结果验证

pip list | grep Flask
# 输出应为 Flask==2.0.1

5. 版本冲突处理

# 假设系统中已存在 Flask==2.1.0
pip install -r requirements.txt
# 输出：Conflict: Flask 2.1.0 is incompatible with Flask==2.0.1

解决办法：

• 手动升级 requirements.txt 中的版本：

  Flask==2.1.0
  requests>=2.25.1

• 或使用 pip install --ignore-installed Flask 强制安装指定版本。

六、源码解析

1. pip 的依赖解析逻辑

pip 的核心逻辑在 pip/_internal/operations/install.py 中实现。其核心流程如下：

1. 解析 requirements.txt 中的依赖项。
2. 根据版本约束查找可用版本。
3. 使用 pip._vendor.packaging.version 模块进行版本比较。
4. 安装时调用 pip._internal.index.package_index.PackageIndex 获取包信息。

关键代码片段：

# pip/_internal/operations/install.py
def install_packages(...):
    for req in requirements:
        version = parse_version(req.version)
        if not version.is_compatible(current_version):
            raise InstallationError("Version conflict")

2. pip freeze 的源码逻辑

pip freeze 的核心逻辑在 pip/_internal/commands/freeze.py 中，其主要功能是遍历已安装的包并输出版本信息。

# pip/_internal/commands/freeze.py
def run(...):
    for dist in get_installed_distributions(...):
        print(f"{dist.project_name}=={dist.version}")

七、进阶使用

1. 管理开发依赖和生产依赖

常见做法是使用两个 requirements 文件：

• requirements.txt：生产依赖。
• requirements-dev.txt：开发依赖。

# requirements.txt
Flask==2.0.1
requests==2.25.1

# requirements-dev.txt
pytest==7.0.0
black==22.3.0

安装开发依赖：

pip install -r requirements-dev.txt

2. 使用 pip-tools 管理复杂依赖

pip-tools 提供了 pip-compile 工具，可以生成更精确的依赖文件。

pip install pip-tools
pip-compile requirements.in

requirements.in 示例：

Flask>=2.0.1
requests>=2.25.1

输出 requirements.txt：

Flask==2.0.1
requests==2.25.1

3. 结合 pipenv 或 poetry 的替代方案

对于复杂项目，推荐使用 pipenv 或 poetry 管理依赖。它们支持更高级的功能，如虚拟环境管理、依赖锁定等。

八、性能与工程实践

1. 性能优化

• 避免冗余依赖：定期清理 requirements.txt 中的过期依赖。
• 使用 --no-binary 选项：加速安装，但可能导致兼容性问题。
• 并行安装：使用 pip install -r requirements.txt --no-cache-dir 加速安装。

2. 安全风险

• 依赖漏洞：某些包可能包含安全漏洞（如 requests 的已知漏洞）。
• 解决方案：使用 pip-audit 或 Trivy 扫描已安装的包。

3. 异常处理

• 版本冲突：使用 pip install --upgrade 或手动调整 requirements.txt。
• 网络问题：使用 --index-url 指定私有仓库，或配置 pip.conf。

九、常见问题与踩坑

1. 版本冲突导致安装失败

现象：

ERROR: Could not find a version that satisfies the requirement Flask==2.0.1

原因：

• 指定的版本不存在于 PyPI。
• 系统中已安装的包版本与 requirements.txt 冲突。

解决办法：

• 使用 pip install --upgrade 更新包。
• 检查 requirements.txt 中的版本是否有效。

2. 依赖递归过深导致安装失败

现象：

ERROR: Could not find a version that satisfies the requirement abc

原因：

• 依赖链过长，导致 pip 无法解析版本。

解决办法：

• 使用 pip install --no-deps 安装主包，手动安装依赖。
• 使用 pip install --ignore-installed 强制安装。

3. 不同环境的依赖不一致

现象：

• 开发环境和生产环境的依赖版本不一致。
• 导致功能异常或部署失败。

解决办法：

• 使用 requirements.txt 统一管理依赖。
• 配合 CI/CD 工具（如 GitHub Actions）进行依赖验证。

十、最佳实践

1. 生成 requirements.txt 的最佳实践

• 使用 pip freeze 精简依赖：结合 pip freeze 和手动编辑，去除冗余依赖。
• 分环境管理依赖：区分生产依赖和开发依赖。
• 定期更新依赖：使用 pip list --outdated 检查过期包。

2. 使用 requirements.txt 的最佳实践

• 在部署前验证依赖：使用 pip install -r requirements.txt --dry-run 检查安装可行性。
• 避免使用 == 精确版本：除非必要，否则使用 >= 或 <= 提高兼容性。
• 结合虚拟环境使用：确保不同项目的依赖隔离。

3. 替代方案的建议

• 简单项目：使用 requirements.txt。
• 复杂项目：使用 pipenv 或 poetry。
• 企业级项目：结合 pip-audit 和 Trivy 管理依赖安全。

十一、总结

requirements.txt 是 Python 项目依赖管理的核心工具，其原理基于 pip 的依赖解析算法和版本约束机制。通过合理使用 requirements.txt，可以确保不同环境的依赖一致性，提高团队协作效率。然而，其局限性在于无法处理复杂的依赖关系，且在版本冲突时可能需要手动干预。

在实际开发中，应根据项目复杂度选择合适的依赖管理方案。对于简单项目，requirements.txt 是轻量且高效的工具；对于复杂项目，推荐使用 pipenv 或 poetry。同时，务必关注依赖安全和性能优化，确保项目稳定运行。

通过深入理解 requirements.txt 的原理和使用场景，开发者可以更好地应对依赖管理中的挑战，提升项目质量和可维护性。