将代码推送至Heroku失败及gunicorn命令未找到问题求助

问题概述 #

推送代码到Heroku时反复收到failed to push some refs错误，提示pre-receive hook declined；即使gunicorn已写入requirements.txt、Procfile配置正确，运行时仍提示gunicorn: command not found，甚至heroku run bash中Python也无法识别。本地运行正常，已尝试虚拟环境推送、调整buildpack、清除缓存等操作均无效。

核心原因分析 #

从日志判断，Heroku的Python运行环境未正确初始化，依赖包未完成安装，导致gunicorn和Python命令无法被识别。大概率是buildpack优先级、配置文件格式或目录结构出现问题。

解决方案 #

1. 调整Buildpack优先级，确保Python Buildpack优先执行 #

Heroku按buildpack顺序执行流程，若apt buildpack排在Python之前，可能破坏Python环境：

• 查看当前buildpack列表：

  heroku buildpacks
  

• 移除不必要的apt buildpack（若无需额外系统依赖）：

  heroku buildpacks:remove heroku-community/apt
  

• 将Python buildpack设为第一个执行：

  heroku buildpacks:add --index 1 heroku/python
  

2. 严格检查配置文件格式 #

• runtime.txt：必须严格写为python-3.11.10，不能有空格、多余换行或字符，Heroku对版本格式要求极高，格式错误会导致无法识别指定Python版本，甚至 fallback到旧版本或无Python环境。
• requirements.txt：
  • 明确指定gunicorn版本（避免兼容问题），例如gunicorn==21.2.0
  • 确保文件为纯文本格式，无Windows换行符（可使用dos2unix requirements.txt转换）
  • 检查文件是否被.gitignore排除，执行git ls-files | grep requirements.txt确认已提交到git仓库

3. 彻底重置应用环境并重新部署 #

• 清除Heroku缓存：

  heroku repo:purge_cache -a college-compass
  

• 重新设置Python buildpack：

  heroku buildpacks:set heroku/python
  

• 强制推送代码：

  git push heroku main --force
  

4. 确认代码目录结构 #

确保以下核心文件都在git仓库根目录，而非子文件夹内：

• Procfile（内容为web: gunicorn app:app）
• requirements.txt
• runtime.txt
• app.py

执行git ls-files查看根目录文件列表，确认这些文件存在且路径正确。

5. 查看完整构建日志排查依赖安装问题 #

不要仅依赖“构建正常”的提示，查看完整构建日志确认依赖是否成功安装：

heroku logs --build

重点关注是否出现Collecting gunicorn、Installing collected packages等日志，若存在下载失败、权限错误等提示，针对性解决（如检查依赖包名称是否正确）。

6. 强制指定Python/gunicorn路径（临时 workaround） #

若环境变量异常，可在Procfile中指定完整路径：

web: /app/.heroku/python/bin/gunicorn app:app

部署后再次测试运行状态。

内容的提问来源于stack exchange，提问作者Arushi Shah