部署Flask应用到Heroku出现Push rejected编译失败如何解决

按优先级排查修复 #

1. 先修正依赖配置（80%的此类报错由requirements.txt问题导致） #

• 确认requirements.txt位于项目根目录，而非任何子文件夹内，Heroku构建时仅会识别根目录下的依赖声明文件。
• 不要直接用全局环境的pip freeze导出依赖：全局环境会混入大量本地系统专属包、虚拟环境残留包，这类包在Heroku的Linux编译环境下大概率安装失败。正确操作是激活项目专属虚拟环境后，仅导出项目实际调用的依赖，Flask项目必须显式声明两个核心依赖：

  Flask==<你本地开发验证通过的版本号>
  gunicorn==<对应兼容版本号>
  

  其余依赖按需添加，若遇到特定包版本安装失败，可暂时移除版本号限定测试是否为版本兼容问题。
• 检查所有依赖包名、版本号拼写正确，不存在已从PyPI下架的废弃版本。

2. 修正Procfile进程配置 #

• 确认Procfile为无后缀名文件：Windows系统默认隐藏已知文件后缀，很多用户误存为Procfile.txt，Heroku无法识别该配置会直接导致编译/启动失败。
• 确认Procfile位于项目根目录，文件内容严格遵循格式要求，Flask项目标准web进程配置写法为：

  web: gunicorn <你的Flask入口文件名>:app
  

  例：若启动逻辑写在app.py、Flask实例名为app，配置即为web: gunicorn app:app。注意使用英文半角冒号，不要加多余注释、特殊字符或首尾空格。

3. 明确Python版本避免兼容问题 #

Heroku构建时默认拉取最新稳定版Python，若你的代码或依赖适配旧版本Python，会触发编译失败。可在项目根目录新建runtime.txt，写入你本地开发跑通的Python版本，格式如下：

python-3.9.13

注意填写的版本号必须在Heroku官方支持的Python版本列表内，版本号格式错误也会触发编译报错。

4. 从构建日志定位精准报错 #

不要仅看末尾的通用拒绝提示，向上翻找构建日志中带ERROR标记的红色行，常见的具体报错包括：

• 依赖包C扩展编译失败：可执行heroku buildpacks:add --index 1 heroku/python重置官方Python构建包重试
• 入口文件不存在：核对Procfile里写的入口文件名和实际文件名一致，注意Heroku环境对文件名大小写敏感
• 端口绑定错误：不要在代码里硬编码监听端口，使用Heroku动态分配的PORT环境变量即可

本地预验证步骤 #

推送到Heroku前先在本地虚拟环境执行两步验证，可排除90%的配置问题：

• 执行pip install -r requirements.txt，确认所有依赖无报错安装完成
• 执行gunicorn <入口文件名>:app，确认项目可以通过gunicorn正常启动访问

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