pip在安装第三方包时，大部分用户只会执行pip install requests这样的命令。默认情况下pip通过HTTPS从PyPI下载包，传输层加密基本能防止数据被窃听，但如果PyPI账号被入侵、镜像站被投毒或者本地缓存被篡改，仅靠HTTPS就无法发现包内容已经改变。要获得更强的安全保障，pip提供了哈希验证机制，通过比对下载文件的SHA256等摘要值，确保安装的包与发布者声明的内容完全一致。这种验证不是自动开启的，需要先为每个依赖生成并记录哈希，然后在安装时加上--require-hashes参数强制校验。

一、pip hash验证解决的问题与哈希算法选择

pip默认的安装流程是：解析依赖关系、从索引下载包、解包并执行setup.py或安装wheel。下载阶段虽然依赖HTTPS证书校验，但HTTPS只能确认你正在与某个域名通信，不能确认该域名提供的文件就是原始发布者上传的那个文件。例如某个镜像站可能缓存了被修改过的包，或者攻击者控制了镜像源，这时TLS加密反而成了掩护。

哈希验证则是从文件内容层面进行校验。发布者在构建包之后会计算一个摘要值，用户下载完成后对本地文件计算同样的摘要，两者一致才说明文件在传输和存储过程中没有被改动。pip内置了pip hash命令，可以方便地计算文件哈希。运行pip hash --help可以看到它支持的算法，包括sha256、sha384、sha512等。对于安全用途，sha256已经足够，sha512计算更慢但抗碰撞性更强。

下面演示对一个实际下载的wheel包计算哈希：

pip hash requests-2.31.0-py3-none-any.whl

执行后会输出类似以下内容：

requests-2.31.0-py3-none-any.whl:
    sha256=942c5a758f98d790eaed1a29cb6eefc7ffb0d1cf7af05c3d2791656dbd6ad1e

这里得到的十六进制摘要字符串需要记录下来，并在后续安装时作为可信值使用。

二、生成哈希并构建带哈希的requirements.txt

想让pip在安装时校验哈希，必须把哈希值写入依赖描述文件。最直接的方式是手动编辑requirements.txt。每个依赖行除了写包名和版本外，还要追加--hash=算法:摘要。例如锁定requests 2.31.0的sha256哈希，可以写成：

requests==2.31.0 --hash=sha256:942c5a758f98d790eaed1a29cb6eefc7ffb0d1cf7af05c3d2791656dbd6ad1e

如果希望同时接受多个算法的哈希，可以在同一行中写多个--hash参数。pip在安装时会计算文件的对应算法摘要，只要有一个匹配就认为通过。这便于在不同平台或不同构建版本之间做兼容，但也会稍微降低严格性，因为攻击者只要改出一个匹配任一弱算法的文件就可能通过。

手动维护哈希对于两三个依赖还能接受，但如果项目有几十个直接依赖，每个依赖又有十几个传递依赖，逐个手动生成哈希非常痛苦。此时可以使用pip-tools这类工具，它能在requirements.in中写出顶层依赖，然后通过pip-compile --generate-hashes自动生成带有所有传递依赖及哈希的锁定文件。这样既能保证完整性，又能保证可重复安装。

三、启用--require-hashes的安装流程与实际限制

有了带哈希的requirements.txt后，安装命令需要显式加上--require-hashes，例如：

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

该参数会让pip进入严格模式。在这种模式下，pip会检查requirements.txt中的每一个依赖，包括传递依赖，都必须有对应的--hash条目。如果某个依赖没有哈希，pip会直接报错，不会继续下载。例如当你只锁定了requests，但requests又依赖urllib3，而urllib3没有写哈希，安装就会失败并提示：

ERROR: In --require-hashes mode, all requirements must have their versions pinned with ==. Specifier 'urllib3' is not allowed.

这也是很多开发者第一次启用--require-hashes时遇到的问题。解决方法是不要只写顶层依赖，必须把完整依赖树都锁定进来。使用pip-compile --generate-hashes或pip download配合脚本可以自动化完成这件事。需要注意的是，--require-hashes还要求所有依赖都固定版本，不能使用范围版本如requests>=2.0，因为范围版本无法预先确定哈希。

另外，--require-hashes不支持直接从VCS安装依赖，例如git+https://...，也不支持本地文件路径或目录安装。这类安装方式无法提前计算哈希，会在严格模式下被禁止。因此如果项目中有从内部Git仓库安装的私有包，需要先把它打包成wheel并生成哈希，或者拆分成单独的安装步骤，避免和--require-hashes混用。

四、在持续集成与部署环境中使用哈希验证

把带哈希的锁定文件纳入版本控制是保证部署一致性的关键。每次构建环境时都从锁定文件安装，这样开发环境、测试环境和生产环境使用的依赖文件完全一致，哈希校验可以防止构建服务器上的缓存被污染。对于Docker镜像构建，可以在Dockerfile中写：

COPY requirements.txt .
RUN pip install --no-cache-dir --require-hashes -r requirements.txt

这里--no-cache-dir让pip不使用本地缓存，确保每次从索引重新下载并校验哈希。虽然会增加下载时间，但能避免缓存中的旧文件被错误使用。如果构建环境使用了内部镜像源，还需要确保镜像源本身不会修改文件内容，否则哈希校验会失败。

升级依赖时不能只修改版本号，必须重新运行pip-compile --generate-hashes或手动执行pip hash生成新哈希。如果只改版本而不更新哈希，安装会报哈希不匹配错误。这个错误本身也是安全提示，说明下载到的文件与预期不一致。处理时不要盲目删除哈希，而应确认新版本是否来自可信源，再更新锁定文件并提交变更。

哈希验证并非万能，它依赖发布者提供的哈希是可信的。如果PyPI源被完全攻破并且攻击者同时篡改了包文件和发布哈希，接收方无法通过哈希发现异常。但结合HTTPS、PyPI的审计日志以及哈希固定，已经能把供应链攻击的门槛提高很多。对于安全敏感的项目，还应当使用独立的哈希发布渠道或使用带有签名的包格式作为补充。