如何查看Heroku构建缓存CACHE_DIR内容以修复依赖不匹配问题

方法1：通过构建钩子导出缓存内容 #

Heroku的构建缓存仅在构建阶段可访问，你可以通过预编译钩子将缓存打包导出后下载到本地查看：

• 在项目根目录新建bin/pre_compile文件，这是Heroku Python构建包原生支持的预编译执行钩子，写入以下内容：

#!/usr/bin/env bash
# 打包完整构建缓存并复制到构建输出目录，后续可直接访问
tar -czf heroku_cache_backup.tar.gz $CACHE_DIR
cp heroku_cache_backup.tar.gz $BUILD_DIR/

• 本地执行命令给钩子文件添加可执行权限：chmod +x bin/pre_compile
• 提交改动并推送到Heroku触发构建：git add bin/pre_compile && git commit -m "export build cache" && git push heroku main
• 构建完成后通过Heroku CLI下载缓存包到本地：heroku run cat heroku_cache_backup.tar.gz > local_cache.tar.gz
• 本地解压local_cache.tar.gz即可查看完整的构建缓存内容
• 导出完成后记得删除bin/pre_compile文件并推送到Heroku，避免后续每次构建都生成冗余的缓存包

方法2：临时导出缓存（无需长期修改项目代码） #

如果你不想在项目中留存钩子文件，也可以使用一次性配置完成导出：

• 本地执行命令临时设置构建参数：heroku config:set BUILD_COMMAND='tar -czf cache.tar.gz $CACHE_DIR && cp cache.tar.gz .'
• 推送代码触发构建后下载缓存包，操作完成后执行heroku config:unset BUILD_COMMAND清除配置即可

修复requirements.txt的参考方案 #

拿到缓存内容后，你可以快速梳理出正确的依赖版本：

• 优先查看缓存内/.heroku/python/lib/python<你的Python版本号>/site-packages/目录，所有实际安装的第三方依赖都存放在这里，每个依赖会自带版本标识文件，例如pandas-2.0.3.dist-info，直接将所有依赖名加对应的版本号整理进requirements.txt即可
• 如果存在自行编译的二进制依赖或者无PyPI源的私有包，可以直接从缓存中复制对应的包文件到项目目录，在requirements.txt中通过本地路径引用即可，格式为./path/to/your/package.whl
• 修复完成后建议先创建一个空的Heroku测试应用推送验证，确认无依赖报错后再更新生产环境

注意事项 #

• 导出的缓存包包含应用的所有构建历史产物，可能存在敏感配置信息，不要对外公开分发
• 如果你已经清理了生产环境的构建缓存，可以先回退到清理缓存前的代码版本，导出旧版本的缓存后再进行依赖修复

内容的提问来源于stack exchange，提问作者Tapple Gao