跳转到主要内容
如果要监控迁移失败,请监听 Illuminate\Database\Events\MigrationFailed。当单个迁移在执行过程中发生异常时,Laravel 会先触发此事件,然后重新抛出该异常。 这并不是自动重新执行迁移的机制。它是一个用于将失败的迁移名称、是 up 还是 down 失败,以及原始异常传递给日志和通知的事件。

事件包含的信息

MigrationFailed 继承自 MigrationEvent,并公开关于单个迁移的以下值。 除了 name 之外再记录 migration::class,即使在无法获取文件名的路径中也能确定目标迁移。使用 migration->getConnection() 还可以确认迁移显式指定的连接名称。

注册监听器

在应用的服务提供者中注册事件,并将结构化的上下文和原始异常传递给日志。
让监听器专注于记录失败,不要在其中修改架构或重新执行迁移。由于原始异常会在事件之后被重新抛出,php artisan migrate 和 php artisan migrate:rollback 仍会以失败结束。

触发顺序

对于普通的单个迁移,Migrator 按以下顺序触发事件。 MigrationEnded 只在执行成功时触发。如果迁移的处理,或执行过程中触发的事件的监听器抛出异常,就会进入 runMigration 的异常处理,并触发 MigrationFailed。 此外,如果在批次中途重新抛出异常,剩余的迁移将不会执行。因此,失败的批次不一定会触发 MigrationsEnded。不要只用同一个事件来同时处理批次完成和失败。

与事务的关系

当数据库的 Schema Grammar 支持架构事务,且迁移的 withinTransaction 处于启用状态时,Laravel 会用事务包裹执行过程。
如果在这一路径中处理失败,MigrationFailed 会在事务回滚之后触发。但在以下情况下,数据库不一定能回滚所有操作:
  • 所使用的数据库或 Schema Grammar 不支持架构事务
  • 迁移中指定了 public $withinTransaction = false
  • 数据库不将 DDL 作为事务处理
因此,不要仅凭收到此事件就判断架构已恢复到原始状态。在发生失败的环境中,请先确认实际的架构和 migrations 表的状态,然后再进行恢复。

区分 up 与 down 的失败

回滚失败也通过同一事件通知。检查 method,即可在应用与撤销时区分通知目标和运维流程。
当 down 失败时,异常发生在目标迁移从 migrations 表中删除之前。Migrator 只在 down 正常完成后才执行删除,因此失败后请同时确认实际的架构和记录。

监控与通知的边界

MigrationFailed 在执行部署或手动 Artisan 命令的进程内同步处理。将通知放入队列,就可以在不掩盖迁移命令本身失败的前提下,把通知的投递分离到后续处理中。 但应避免在监听器中重新执行失败的迁移。在同一命令尚未结束时重新执行,会使锁、部分应用的 DDL 以及部署顺序等问题变得复杂。需要重新执行时,请先修复原因并确认状态,再作为运维流程执行。

在测试中确认事件

准备一个会失败的测试用迁移,确认 Artisan 命令失败,并且事件持有导致失败的异常。不要把测试用迁移放在生产环境的扫描范围内。
Event::fake 会记录事件,因此可以与应用实际的通知处理分开测试。是否发生回滚、DDL 是否会部分残留,请使用所用数据库和 Schema Grammar 编写单独的集成测试来确认。

总结

  • 单个迁移失败时,MigrationFailed 会传递 migration、method、name 和 exception。
  • MigrationEnded 只在成功时触发,MigrationsEnded 只在批次完整执行完毕时触发。
  • 事务和 DDL 的行为因数据库而异,因此不要把该事件当作回滚的保证。
  • 将监听器限定于监控和通知,重新执行和恢复应在确认原因和架构后作为运维流程进行。

参考的一手资料

最后修改于 2026年11月15日