> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 MigrationFailed 事件处理迁移失败

> 使用 Laravel 13 的 MigrationFailed 事件，理解失败迁移的信息、事务边界以及监控与测试的设计。

如果要监控迁移失败，请监听 `Illuminate\Database\Events\MigrationFailed`。当单个迁移在执行过程中发生异常时，Laravel 会先触发此事件，然后重新抛出该异常。

这并不是自动重新执行迁移的机制。它是一个用于将失败的迁移名称、是 `up` 还是 `down` 失败，以及原始异常传递给日志和通知的事件。

## 事件包含的信息

`MigrationFailed` 继承自 `MigrationEvent`，并公开关于单个迁移的以下值。

| 属性 | 类型 | 内容 |
| - | - | - |
| `migration` | `Migration` | 正在执行的迁移实例 |
| `method` | `string` | 被调用的方法，通常为 `up` 或 `down` |
| `name` | `string\|null` | 迁移名称。根据执行路径可能为 `null` |
| `exception` | `Throwable` | 导致失败的异常 |

除了 `name` 之外再记录 `migration::class`，即使在无法获取文件名的路径中也能确定目标迁移。使用 `migration->getConnection()` 还可以确认迁移显式指定的连接名称。

## 注册监听器

在应用的服务提供者中注册事件，并将结构化的上下文和原始异常传递给日志。

```php theme={null}
<?php

namespace App\Providers;

use Illuminate\Database\Events\MigrationFailed;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Event::listen(MigrationFailed::class, function (MigrationFailed $event): void {
            Log::error('Database migration failed.', [
                'migration' => $event->name,
                'class' => $event->migration::class,
                'method' => $event->method,
                'connection' => $event->migration->getConnection(),
                'exception' => $event->exception,
            ]);
        });
    }
}
```

让监听器专注于记录失败，不要在其中修改架构或重新执行迁移。由于原始异常会在事件之后被重新抛出，`php artisan migrate` 和 `php artisan migrate:rollback` 仍会以失败结束。

## 触发顺序

对于普通的单个迁移，`Migrator` 按以下顺序触发事件。

```mermaid theme={null}
flowchart TD
    A["MigrationsStarted<br>批次开始"] --> B["MigrationStarted<br>单个迁移开始"]
    B --> C{"up / down 成功?"}
    C -->|成功| D["MigrationEnded<br>单个迁移完成"]
    D --> E["下一个迁移"]
    E --> F["MigrationsEnded<br>批次完成"]
    C -->|异常| G["MigrationFailed<br>保存异常"]
    G --> H["重新抛出原始异常"]
```

`MigrationEnded` 只在执行成功时触发。如果迁移的处理，或执行过程中触发的事件的监听器抛出异常，就会进入 `runMigration` 的异常处理，并触发 `MigrationFailed`。

此外，如果在批次中途重新抛出异常，剩余的迁移将不会执行。因此，失败的批次不一定会触发 `MigrationsEnded`。不要只用同一个事件来同时处理批次完成和失败。

## 与事务的关系

当数据库的 Schema Grammar 支持架构事务，且迁移的 `withinTransaction` 处于启用状态时，Laravel 会用事务包裹执行过程。

```php theme={null}
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('orders', function (Blueprint $table): void {
            $table->string('status');
        });
    }
};
```

如果在这一路径中处理失败，`MigrationFailed` 会在事务回滚之后触发。但在以下情况下，数据库不一定能回滚所有操作：

* 所使用的数据库或 Schema Grammar 不支持架构事务
* 迁移中指定了 `public $withinTransaction = false`
* 数据库不将 DDL 作为事务处理

因此，不要仅凭收到此事件就判断架构已恢复到原始状态。在发生失败的环境中，请先确认实际的架构和 `migrations` 表的状态，然后再进行恢复。

## 区分 `up` 与 `down` 的失败

回滚失败也通过同一事件通知。检查 `method`，即可在应用与撤销时区分通知目标和运维流程。

```php theme={null}
Event::listen(MigrationFailed::class, function (MigrationFailed $event): void {
    $operation = $event->method === 'down' ? 'rollback' : 'migrate';

    Log::critical('Migration operation failed.', [
        'operation' => $operation,
        'migration' => $event->name ?? $event->migration::class,
        'exception' => $event->exception,
    ]);
});
```

当 `down` 失败时，异常发生在目标迁移从 `migrations` 表中删除之前。`Migrator` 只在 `down` 正常完成后才执行删除，因此失败后请同时确认实际的架构和记录。

## 监控与通知的边界

`MigrationFailed` 在执行部署或手动 Artisan 命令的进程内同步处理。将通知放入队列，就可以在不掩盖迁移命令本身失败的前提下，把通知的投递分离到后续处理中。

但应避免在监听器中重新执行失败的迁移。在同一命令尚未结束时重新执行，会使锁、部分应用的 DDL 以及部署顺序等问题变得复杂。需要重新执行时，请先修复原因并确认状态，再作为运维流程执行。

## 在测试中确认事件

准备一个会失败的测试用迁移，确认 Artisan 命令失败，并且事件持有导致失败的异常。不要把测试用迁移放在生产环境的扫描范围内。

```php theme={null}
<?php

namespace Tests\Feature;

use Illuminate\Database\Events\MigrationFailed;
use Illuminate\Support\Facades\Event;
use RuntimeException;
use Tests\TestCase;

class MigrationFailureTest extends TestCase
{
    public function test_failed_migration_dispatches_event(): void
    {
        Event::fake([MigrationFailed::class]);

        $this->artisan('migrate', [
            '--path' => 'tests/Fixtures/migrations/2026_01_01_000000_fail.php',
        ])->assertFailed();

        Event::assertDispatched(MigrationFailed::class, function (MigrationFailed $event): bool {
            return $event->method === 'up'
                && $event->exception instanceof RuntimeException;
        });
    }
}
```

`Event::fake` 会记录事件，因此可以与应用实际的通知处理分开测试。是否发生回滚、DDL 是否会部分残留，请使用所用数据库和 Schema Grammar 编写单独的集成测试来确认。

## 总结

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

## 参考的一手资料

* [Laravel 官方文档：迁移事件](https://github.com/laravel/docs/blob/13.x/migrations.md#events)
* [Laravel 官方文档：事件监听器](https://github.com/laravel/docs/blob/13.x/events.md#registering-events-and-listeners)
* [Framework 13.x: MigrationFailed](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Events/MigrationFailed.php)
* [Framework 13.x: MigrationEvent](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Events/MigrationEvent.php)
* [Framework 13.x: Migrator 的事件触发](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Migrations/Migrator.php#L435-L460)
* [Framework 13.x: Migration 基类](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Migrations/Migration.php)


## Related topics

- [数据库迁移](https://kawax.biz/zh-CN/migrations.md)
- [进阶主题](https://kawax.biz/zh-CN/advanced/index.md)
- [快速开始 - GitHub Copilot SDK for Laravel](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/getting-started.md)
- [事件与监听器](https://kawax.biz/zh-CN/events.md)
- [React 入门 —— 与 Inertia × Laravel 搭配使用的基础](https://kawax.biz/zh-CN/blog/react-introduction.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.