Django部署Heroku推送main分支报pre-receive hook declined错误

这个报错是Heroku服务端在接收代码推送的预检查、构建环节执行失败，主动拒绝了代码合入，和Git本地配置、仓库地址没有关系。你看到的最后两行是通用报错提示，真正的错误原因在git push heroku main执行时输出的前置滚动日志里，绝大多数都是配置不符合Heroku Django部署要求导致的，结合《Django for Beginners》第3章Pages App的部署场景，高频问题和排查方案如下。

• 第一步先定位具体错误点
  重新执行git push heroku main，往上翻输出的日志，找到第一条带!或者ERROR标记的行，这才是真正的失败原因，最后两行的pre-receive hook declined只是最终结果提示，没有定位价值。
• 检查核心部署文件是否合规（占这类报错的70%以上）
  所有部署配置文件必须放在manage.py所在的项目根目录，不能放到子文件夹里；Windows系统注意关闭“隐藏已知文件扩展名”选项，避免文件后缀名错误：
  • Procfile：无任何文件后缀，内容必须和教程要求一致：web: gunicorn config.wsgi --log-file -，注意gunicorn拼写、wsgi路径要对应项目中config目录下的wsgi文件，不要写错项目名。
  • requirements.txt：必须包含所有项目依赖，尤其不能漏gunicorn，执行pip freeze > requirements.txt生成即可，注意删除文件中带@ file:///开头的本地路径依赖行，这类路径Heroku服务端无法访问，会导致依赖安装失败。
  • runtime.txt：明确指定Heroku兼容的Python版本，比如写python-3.10.13，不要用3.7及以下的已停服版本，否则Heroku无法匹配运行环境直接构建失败。
• 检查Django配置项
  打开项目的settings.py确认以下配置：
  • ALLOWED_HOSTS中添加你的Heroku应用域名，格式为<你的heroku应用名>.herokuapp.com，调试阶段可以临时设为['*']排除配置问题。
  • 文件末尾添加django_heroku.settings(locals())（对应教程中要求安装的django-heroku包），自动配置静态文件路径、环境变量读取等适配逻辑，否则会出现静态文件收集失败、SECRET_KEY读取失败等问题。
  • 确认所有自己创建的app（比如章节里的pages app）都已经添加到INSTALLED_APPS列表中，并且所有代码改动已经提交到Git。
• 检查分支与构建配置
  • 执行git status确认所有改动都已经commit，未提交的改动不会被推送到Heroku，会出现本地改了配置但远端还是旧版本的问题。
  • 如果你本地主分支名是master不是main，推送时需要执行git push heroku master:main做分支映射，避免分支不匹配。
  • 执行heroku buildpacks:set heroku/python确认Heroku应用的构建包是Python，如果你之前给这个应用设置过其他语言的构建包，会出现无法识别Python项目的问题。
• 本地预校验
  本地激活虚拟环境后执行python manage.py check，确认本地项目没有配置错误，再执行gunicorn config.wsgi确认gunicorn可以正常启动服务，排除本地代码本身的bug。

按以上步骤排查后，绝大多数第3章的部署报错都可以解决，如果仍有问题，直接根据push日志里的第一条具体错误（比如依赖缺失、模块找不到、静态文件收集失败）对应修正即可。

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