Rails应用部署至Heroku时含数据库迁移的构建推送失败陷入两难

核心问题拆解 #

• 部署阻塞的直接触发逻辑：Rails应用在Heroku发布阶段会自动扫描待执行迁移列表，发现存在未跑的迁移就会强制中止发布流程
• 死循环的形成原因：当前线上运行的旧构建包中没有新增的迁移文件，直接在线上执行迁移命令时，代码引擎找不到对应的迁移逻辑，自然不会产生任何实际效果；但要把带迁移文件的新构建推上线，又会被发布阶段的迁移检查拦截，形成逻辑闭环
• 迁移不生效的本质原因：不管是发布阶段自动执行迁移，还是手动在线上跑迁移命令，都遇到了Heroku运行环境内置的Bundler版本和项目bundle安装的Bundler版本冲突问题，命令在初始化加载阶段就异常中断，根本没走到执行迁移的代码分支，满屏的already initialized constant就是版本冲突的典型信号，不是无意义的运行噪音。之前推送时报错，本质就是发布阶段自动跑迁移时被这个版本问题中断，没有真正完成迁移流程，才会触发pending migration的报错。

实操解决步骤 #

1. 临时关闭发布阶段的迁移拦截机制，打破死循环
   执行命令：
   heroku config:set DISABLE_DATABASE_MIGRATION_GUARD=true -a 你的应用ID
   该配置会让Heroku跳过发布环节的待迁移检查，允许包含迁移文件的新构建正常完成部署。
2. 修复Bundler版本冲突问题，保证迁移命令可正常执行
   • 本地执行bundler -v查看项目实际使用的Bundler版本
   • 打开项目根目录的Gemfile.lock，把文件末尾的BUNDLED WITH字段版本号调整为和本地实际版本完全一致，消除系统内置Bundler和项目安装Bundler的版本差
   • 本地重新执行bundle install，把修正后的Gemfile.lock提交到本地git仓库
3. 推送修正后的代码到Heroku
   正常执行git push heroku master，因为已经临时关闭了迁移拦截，这一步不会再出现之前的发布报错，能顺利完成新构建的部署流程。
4. 在新部署的环境上手动执行数据库迁移
   执行命令：heroku run bin/rails db:migrate -a 你的应用ID
   这一步因为新dyno已经加载了完整的迁移文件，且Bundler版本冲突已经修复，不会再只输出警告，会正常执行所有待运行的迁移任务，创建缺失的Users、Alerts、Contacts表。
5. 恢复发布阶段的保护机制
   确认迁移执行完成、应用功能正常后，执行命令关闭临时配置：
   heroku config:unset DISABLE_DATABASE_MIGRATION_GUARD -a 你的应用ID

避坑提醒 #

• 不要在旧的运行环境里反复尝试执行迁移命令，旧环境的代码版本中根本不存在对应的迁移文件，就算解决了Bundler问题，也会因为找不到迁移类直接报错，完全无效
• 关闭发布迁移检查后必须手动执行数据库迁移，不要跳过这一步，否则应用启动后会因为数据库表缺失直接抛出500错误
• 不要把Bundler的版本冲突警告当成正常日志，这些警告出现时，后续的Rails命令其实已经中断执行了，很多人会误以为命令已经跑完，忽略了迁移实际未执行的问题。

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