Laravel Horizon 中失败任务表缺少 UUID 列的问题解析

在 Laravel 11 项目中，当使用 Horizon 处理队列任务时，如果任务执行失败，系统会尝试将失败任务记录到 failed_jobs 表中。然而，许多开发者遇到了一个常见问题：系统报错提示找不到 uuid 列。

问题现象

升级到 Laravel 11 后，当队列任务失败时，系统会抛出数据库错误：

Column not found: 1054 Unknown column 'uuid' in 'field list'

这表明系统尝试向 failed_jobs 表插入数据时，期望找到一个名为 uuid 的列，但该列在实际数据库表中并不存在。

原因分析

在 Laravel 11 中，框架对队列系统进行了改进，现在默认期望 failed_jobs 表包含一个 uuid 字段。这与 Laravel 10 及以下版本的数据库迁移文件有所不同。

许多开发者可能使用了旧版本的迁移文件创建 failed_jobs 表，该表结构仅包含以下字段：

• id (主键)
• connection
• queue
• payload
• exception
• failed_at

解决方案

要解决这个问题，需要确保 failed_jobs 表包含 uuid 字段。以下是两种可行的解决方案：

方案一：创建新的迁移文件

创建一个新的数据库迁移文件来添加 uuid 列：

Schema::table('failed_jobs', function (Blueprint $table) {
    $table->string('uuid')->after('id')->unique();
});

方案二：重新创建表结构

如果数据不重要，可以删除现有表并重新运行 Laravel 11 提供的标准迁移文件，该文件会自动创建包含 uuid 列的正确表结构。

最佳实践

1. 在升级 Laravel 版本时，应仔细检查所有核心迁移文件的变更
2. 对于生产环境，建议先备份数据再执行表结构变更
3. 可以使用 php artisan queue:failed-table 命令重新生成最新的失败任务表迁移文件

总结

这个问题源于 Laravel 11 对队列系统的改进，要求 failed_jobs 表包含 uuid 字段。通过理解这一变更并相应调整数据库结构，可以确保 Horizon 队列监控系统正常工作。对于正在升级项目的开发者，建议检查所有核心数据库表结构是否与新版 Laravel 的要求保持一致。