怎么在requirements.txt中精确控制Python库版本

在 requirements.txt 中精确控制 Python 库版本，绝非简单地在文件里写上 requests==2.31.0 便能彻底解决。真正的精确控制包含三个层层递进的工程要求：首先使用严格等值操作符 == 精确指定直接依赖；其次通过工具自动化展开并固化整棵依赖树中的全部间接传递依赖（Transitive Dependencies）；最后在生产构建阶段引入 SHA-256 内容哈希校验，杜绝远程包篡改与镜像源不一致。本文将按实际开发与部署的操作顺序，详细说明如何规范书写操作符、排查依赖漂移，并使用标准工具链构建 100% 确定性的 Python 运行环境。

一、基础语法：如何使用版本操作符精确指定版本

requirements.txt 是 pip 工具最基础的批处理依赖清单。每一行代表一个依赖项规范。要精确控制某个库，必须选用正确的版本匹配操作符。

在 Python 的 PEP 440 版本规范中，包含多种版本比对符号。对于需要“精确控制”的场景，严格等值操作符 == 是唯一推荐的生产选项。它的作用是强制要求环境中的包版本与声明完全吻合。

# 正确的精确控制写法：包名与版本之间使用 == 连接，不留空格或仅保留标准单空格
requests==2.31.0
fastapi==0.110.0
uvicorn==0.28.0

在实际项目中，很多开发者容易混淆 == 与其他常见符号的边界。了解它们的差异，是避免环境意外升级的第一步：

• 兼容性发行版 ~=（Compatible Release）：例如 requests ~= 2.31.0，其数学含义等价于 >= 2.31.0, < 2.32.0。它允许 pip 自动安装补丁小版本（Patch Releases），但在生产交付文件中，偶发的补丁包依然可能改变内部行为或引入次级缺陷。
• 区间比较符 >= 与 <=：例如 pydantic >= 2.0.0, < 3.0.0。虽然它限制了大版本边界，但次版本（Minor Release）依然会随着时间自动前移，带来非预期的破坏性代码变更风险。
• 无上限开放符 >=：例如 numpy >= 1.24.0。这属于典型的非精确写法，严禁出现在任何生产环境交付文件中。

二、核心难点：直接依赖与传递依赖的“静默漂移”

当我们在 requirements.txt 中将所有行都写成了 == 具体版本，环境就一定绝对稳定了吗？答案是否定的。这也是很多团队遇到“本地运行正常，上线构建却突然报错”的根本原因。

Python 库极少是孤立存在的。以我们常用的 HTTP 库 requests==2.31.0 为例，它在自身打包元数据中声明了自身的依赖：urllib3、certifi、charset-normalizer 和 idna。这些由直接依赖间接引入的下级库，被称为传递依赖（Transitive Dependencies）。

如果你的 requirements.txt 仅写了顶层业务库：

# 缺陷示范：仅写直接引用的顶层库
requests==2.31.0

在首次构建时，pip 会顺着 requests 的元数据去解析 urllib3。假如此时 PyPI 上最新的版本是 urllib3 1.26.18，pip 便会将其下载安装，本地各项测试顺利通过。

然而数月之后，在生产机器上重新运行 pip install -r requirements.txt 构建 Docker 镜像时，urllib3 已经发布了 2.2.0。由于 requests 2.31.0 的元数据允许安装较宽范围的 urllib3，pip 就会在生产构建时静默拉取 urllib3 2.2.0。而 urllib3 2.x 移除了部分废弃属性并对底层系统的 OpenSSL 版本提出了硬性要求，直接导致线上服务启动崩溃。这种现象在工程中被称为依赖漂移（Dependency Drift）。

因此，要想实现真正的“精确控制”，必须把整棵依赖树中的全部叶子节点全部固化到 requirements.txt 中，使 pip 在安装时无需做出任何动态解析决策。

三、实现全量固化的两种标准操作流程

既然传递依赖必须全量锁定，我们该如何高效、准确地生成这份清单？手动去查每个库的子依赖显然不切实际。业界通常有两种标准做法。

方法一：通过全新干净的虚拟环境执行 pip freeze

该方法适用于单次脚本、原型验证或依赖较少的轻量项目。它的核心逻辑是在一个完全空白的环境中只安装所需包，然后将环境现状整体“冻结”输出。

1. 创建并激活全新的干净虚拟环境（确保不继承全局环境中的任何无关模块）：

   python3 -m venv .venv_clean
   source .venv_clean/bin/activate  # Windows: .venv_clean\Scriptsctivate

2. 安装你的业务顶层依赖：

   pip install requests fastapi uvicorn

3. 导出全量固化清单：

   pip freeze > requirements.txt

导出的文件内容将包含所有传递依赖的具体版本：

# 示例输出（明确标为示例，各环境版本可能随时间递进）：
certifi==2024.2.2
charset-normalizer==3.3.2
fastapi==0.110.0
idna==3.6
pydantic==2.6.4
pydantic-core==2.16.3
requests==2.31.0
starlette==0.36.3
typing-extensions==4.10.0
urllib3==1.26.18
uvicorn==0.28.0

方法二：工业级推荐规范——使用 pip-tools 实施双文件分层管理

为了解决 pip freeze 的维护难题，现代 Python 工程普遍采用“声明与锁定分离”的双文件工作流。推荐工具为官方维护的 pip-tools。

1. 安装 pip-tools：

   pip install pip-tools

2. 创建需求声明文件 requirements.in：
   在此文件中，只写人类关心的直接依赖，允许写宽泛范围或只写包名：

   # requirements.in 仅记录顶层直接依赖
   requests>=2.31.0
   fastapi~=0.110.0
   uvicorn

3. 运行 pip-compile 生成全量精确锁定的 requirements.txt：

   pip-compile requirements.in --output-file=requirements.txt

执行完成后，查看自动生成的 requirements.txt，可以看到每个包都锁定了 ==，且附带了详细的 via 溯源注释：

#
# This file is autogenerated by pip-compile with Python 3.11
# by the following command:
#
#    pip-compile requirements.in
#
certifi==2024.2.2
    # via requests
charset-normalizer==3.3.2
    # via requests
fastapi==0.110.0
    # via -r requirements.in
idna==3.6
    # via requests
pydantic==2.6.4
    # via fastapi
requests==2.31.0
    # via -r requirements.in
urllib3==1.26.18
    # via requests
uvicorn==0.28.0
    # via -r requirements.in

当未来需要升级某个特定库（例如单独升级 requests）时，只需执行：

pip-compile --upgrade-package requests requirements.in

pip-tools 会重新计算 requests 及其受影响的传递依赖，其余无关库保持绝对不变，实现了极高精度的受控演进。

四、进阶防护：使用内容哈希（Hash Checking）杜绝篡改与不一致

在版本号完全使用 == 锁定之后，是否就达到了绝对安全？在极端严肃的生产构建、金融业务与合规部署中，答案依然是否定的。

因为版本号只是发布者贴上的字符串标签。在以下场景中，相同版本号的内容仍可能产生差异：

• 企业私有镜像源被污染或覆盖：部分私有 PyPI 源未开启防重写配置，同版本的包可能被重新打包上传，导致代码在不知情下被篡改。
• 供应链投毒与中间人劫持：网络传输过程若遭受 DNS 劫持或恶意篡改，客户端可能下载到注入后门的恶意 Wheel。
• 确定性构建需求（Reproducible Builds）：安全审计要求所有进入生产集群的二进制必须拥有不可逆的数字指纹。

为了杜绝这类隐患，pip 提供了原生支持的哈希检查模式（Hash-Checking Mode）。

使用 pip-tools 可以一键生成带 SHA-256 指纹的锁文件：

pip-compile --generate-hashes requirements.in --output-file=requirements.txt

生成的文件形式如下：

requests==2.31.0     --hash=sha256:58a5da53d0773e1f1db1328217fb936e355871f1f3a563973871143282cfedca     --hash=sha256:942c5a758f98d790eaed1a29cb6eefc3ffb0d1cf7a05f3d2711e8acebba09b45
    # via -r requirements.in
urllib3==1.26.18     --hash=sha256:340458e88905321da6e8ba4e294d819674041871b372e14223d0f4d74611d7a8     --hash=sha256:e8cb44812a43697ebde49a888c3a5040d95c25eb4911f4ee952a2656d7870a37
    # via requests

在生产环境执行安装时，显式指定校验参数：

pip install --require-hashes -r requirements.txt

在此模式下，pip 强制启动最严密的防线：

• 如果 requirements 文件中有任何一个包没有写哈希，pip 直接拒绝执行；
• 如果下载到的文件哈希与文件内标注的值不一致，立即中止安装；
• 严禁动态解析并自动下载未显式列在文件中的任何次级依赖。

五、安装与验证：确保目标环境 100% 确定性执行

在构建流水线（CI/CD）或生产容器打包时，如何验证依赖已被完全控制，且不存在遗漏？推荐以下三项操作：

1. 配合 --no-deps 参数执行极限加速与完整性验证

如果你的 requirements.txt 已经通过编译工具完整锁定了全部直接与间接依赖，在生产部署时可加上 --no-deps：

pip install --no-deps --require-hashes -r requirements.txt

--no-deps 会通知 pip 完全关闭任何依赖拓扑解析逻辑，仅把文件中列出的包如实解压安装。这不仅使安装速度大幅提升数倍，而且如果文件遗漏了某个下级依赖，后续测试或运行时能立即暴露，避免将问题掩盖到生产运行期。

2. 使用 pip check 进行环境闭环自检

安装完成后，在终端立即执行自检命令：

pip check

如果当前虚拟环境内的所有库满足相互之间的依赖约束且无缺失，终端输出：

No broken requirements found.

若存在版本冲突或缺失子包，pip check 会以非零状态码退出并明确打印出不兼容的具体库名，便于自动化流水线阻断发布。

3. 跨平台依赖标记（Environment Markers）处理

若项目在 macOS/Linux 开发，但部分包针对特定平台（如 Windows 专有的 pywin32），直接 pip freeze 可能带入平台特定项，导致 Linux 生产机安装失败。在 requirements.in 中应使用 PEP 508 环境标记加以约束：

# 仅在 Windows 下安装
pywin32==306; sys_platform == 'win32'

pip-compile 能够识别这些标记，并在生成的 requirements.txt 中保留平台环境条件。

六、生产环境精确版本控制总结与自查清单

通过以上分析，我们可以把 Python 项目依赖从开发到生产的生命周期归纳为三层控制架构：

1. 需求声明层：使用 requirements.in 表达业务层直接意图，面向开发者维护；
2. 拓扑锁定层：使用 pip-compile 将意图编译展开为覆盖所有子依赖的 requirements.txt，并嵌入 SHA-256 安全哈希；
3. 确定性运行层：在干净容器或目标机器上，使用 pip install --require-hashes --no-deps 执行严格落地，并配合 pip check 验证。

在提交代码或合并发布分支前，请参照下表完成最终自查：

遵循上述工程规范，团队即可彻底杜绝依赖隐式漂移、版本冲突以及供应链篡改风险，在任何时间、任何计算节点上都能稳定重现完全一致的 Python 运行环境。