本文详解在私有 PyPI 开发场景下，如何安全清除 pip 缓存中特定包、绕过哈希校验失败、强制重下载源码，避免 tox 重建时因缓存陈旧引发的 THESE PACKAGES DO NOT MATCH THE HASHES 错误。
本文详解在私有 pypi 开发场景下，如何安全清除 pip 缓存中特定包、绕过哈希校验失败、强制重下载源码，避免 tox 重建时因缓存陈旧引发的 `these packages do not match the hashes` 错误。
在基于 tox + pyproject.toml/setup.cfg 的 Python 包开发流程中，频繁迭代私有库（如 my_lib）时，pip 缓存常成为“隐形阻碍”：即使执行 pip cache remove my_lib 清除了缓存文件，后续 tox 构建仍可能因缓存残留或哈希不匹配而中断。根本原因在于 pip 的缓存机制与哈希验证逻辑并非完全解耦——尤其当包通过 setup.cfg 中的 install_requires 声明且未显式指定 hash 时，pip 仍可能依据本地已缓存的 .whl 或 .tar.gz 文件的元数据进行校验，导致“文件存在但内容已变”的冲突。
✅ 精准清理单个包缓存（推荐方案）
pip cache remove 命令本身不支持按包名精确匹配（其参数实为路径前缀匹配），直接运行 pip cache remove my_lib 可能误删无关缓存。正确做法是结合 --no-cache-dir 和项目级清理逻辑：
# 步骤1：定位并手动清理该包的缓存目录（更可靠）
pip cache info # 查看缓存根路径，例如 ~/.cache/pip
# 进入缓存目录，查找包含 my_lib 的子目录（通常位于 http/ 或 wheels/ 下）
find "$(pip cache dir)" -type d -name "*my_lib*" -exec rm -rf {} +
# 或使用更安全的模糊匹配（保留其他包）
find "$(pip cache dir)" -type d -path "*/my_lib*" -prune -exec rm -rf {} +⚠️ 注意：pip cache remove --no-cache-dir --project <name> 并非 pip 官方支持的语法（该命令实际会报错），答案中存在误导。官方仅支持 pip cache remove <package_name>，但其行为是前缀匹配，非精确删除。因此，手动 find + rm 是当前最可控的方式。
⚙️ 强制跳过哈希校验 & 重拉最新代码
当 tox 内部调用 pip 安装依赖时，可通过环境变量或命令行参数覆盖默认行为：
-
禁用缓存 + 强制源码构建（推荐）
在 tox.ini 中配置安装命令，确保每次从源码构建，绕过 wheel 缓存与哈希检查：[testenv] deps = # 其他依赖... commands_pre = pip install --no-cache-dir --no-binary=my_lib my_lib或在 pyproject.toml 的 [build-system] 中确保构建后端支持源码分发（如 setuptools>=61.0）。
-
全局禁用哈希校验（仅限开发环境）
pip install --no-deps --force-reinstall --no-cache-dir my_lib
--force-reinstall 确保覆盖已安装版本，--no-deps 避免连带更新依赖（防止意外升级）。
? 提升开发效率的关键实践
-
始终使用可编辑安装（Editable Install）
在 tox 环境中直接安装开发中的包，避免反复打包/上传/安装：[testenv] deps = -e {toxinidir}/../my_lib # 指向本地源码目录此时任何对 my_lib 源码的修改均实时生效，彻底规避缓存问题。
-
配置 tox 使用 --no-cache-dir
在 tox.ini 中统一注入 pip 参数：[testenv] pip_pre_install = true install_command = pip install --no-cache-dir {opts} {packages} -
私有 PyPI 调试技巧
若使用 devpi 或 pypiserver，确认服务端已刷新索引，并在 pip install 时显式指定可信主机：pip install --trusted-host your-private-pypi.com -i https://your-private-pypi.com/simple/ my_lib
综上，解决此类问题的核心逻辑是：优先绕过缓存（--no-cache-dir），其次确保源码实时可用（-e 安装），最后才考虑清理缓存。盲目清除 pip 缓存不仅低效，还可能影响其他项目。将开发流切换至可编辑模式，配合 tox 的路径依赖声明，才是私有库高频迭代的最优解。
