pip install --require-hashes 必须显式启用，因哈希校验是可选安全层，不加该参数时pip完全忽略requirements.txt中的--hash行；所有依赖必须带匹配平台的完整哈希值，缺一则报“Hashes are required”，且不支持-e .等本地路径依赖。
pip install --require-hashes 为什么必须显式启用
不加 --require-hashes，pip 完全忽略 requirements.txt 里的 --hash 行，哪怕它们写得再完整。这不是 bug，是 pip 的默认行为：哈希校验属于“可选安全层”，必须主动开启，否则 pip 当作注释处理。
常见错误现象：pip install -r requirements.txt 成功安装，但实际没校验任何哈希——因为没加参数；或者 CI 脚本里漏了这个 flag，导致上线包仍可能被中间人篡改。
- 必须用
pip install --require-hashes -r requirements.txt - 所有依赖行都得带
--hash=sha256:...，缺一个，pip 直接报错退出（错误信息：Hashes are required in --require-hashes mode） - 如果用了
-e .或本地路径依赖，它们无法参与哈希锁定，pip 会拒绝安装（错误信息：Could not satisfy constraints for 'some-package': installation from path or URL is not allowed）
生成带哈希的 requirements.txt 不能只靠 pip freeze
pip freeze > requirements.txt 输出的是纯版本号，不含哈希，也不能直接用于 --require-hashes 模式。正确做法是先用 pip install 安装目标环境，再用 pip install --require-hashes --no-deps --no-install（已弃用）或更可靠的替代方案。
- 推荐用
pip-compile（来自pip-tools）：运行pip-compile --generate-hashes requirements.in，它会解析依赖树、去 PyPI 拉取每个 wheel 的官方哈希并写入输出文件 - 手动补哈希极容易出错：PyPI 对同一版本可能提供多个 wheel（
cp39-manylinux/cp39-win_amd64），每个对应不同哈希；pip 只接受与当前平台匹配的那个，其他会被忽略或报Hash mismatch - 哈希值必须与下载的文件字节完全一致，包括换行符——用文本编辑器手动修改过文件会导致校验失败
hash 不匹配的三种典型原因和对应检查点
执行 pip install --require-hashes -r requirements.txt 报 Hash mismatch for package xxx，不是网络问题，而是本地环境与哈希记录不一致。
立即学习“Python免费学习笔记（深入）”；
- 平台不匹配：requirements.txt 里写了
--hash=sha256:... --hash=sha256:...多个哈希，但 pip 只尝试匹配当前系统能安装的 wheel 类型（比如 macOS 上不会用win_amd64哈希），如果该平台对应哈希缺失，就报错 - 源被替换：公司私有源（如 Nexus、Artifactory）返回的 wheel 和 PyPI 官方 wheel 字节不同（签名、元数据字段微调等），哈希自然不同；此时必须用私有源重新生成哈希，不能复用 PyPI 版本的哈希
- 依赖被降级或跳过：某包在
requirements.in中指定为django>=4.2，pip-compile锁定到4.2.10并记下哈希；若手动改成django==4.2.9却没更新哈希，必然失败
CI/CD 中启用哈希锁定的关键细节
在 GitHub Actions、GitLab CI 等环境里，光写 --require-hashes 不够，还要确保构建环境干净、wheel 来源唯一、且哈希文件本身受版本控制保护。
- 禁止在 CI 中使用
--find-links或--index-url指向不可信源，否则 pip 可能绕过哈希去下载非预期文件 - 哈希文件（如
requirements.txt）必须提交进 Git，不能每次 CI 临时生成——否则失去“锁定”意义 - Python 版本和架构要与生成哈希时一致：在
ubuntu-22.04+python-3.11下生成的哈希，放到macos-14上运行会因 wheel 不匹配而失败 - 如果项目含 C 扩展（如
numpy），不同平台编译产物哈希不同，建议只锁 source distribution（.tar.gz）哈希，并配--only-binary=:all:强制跳过 wheel，但这会拖慢安装速度
哈希锁定真正起效的前提，是整个链条可控：从生成时的平台、源、工具版本，到安装时的环境、pip 配置、网络路径——任何一环松动，哈希就只是摆设。
