Laravel Supervisor队列管理时failed_jobs表报空uuid唯一键重复错误

问题核心成因 #

Laravel 8及后续版本默认将failed_jobs表的唯一键改为UUID字段，如果你的项目是从低版本升级而来，或是手动修改过队列配置，会缺失UUID自动生成的开关，导致框架写入失败记录时不会生成UUID值，触发字段非空/唯一键约束报错。

分步配置修复 #

• 第一步：修改队列配置文件config/queue.php，找到failed配置块，确保database驱动下开启UUID生成开关：
  正确的failed配置参考：

  'failed' => [
      'driver' => env('QUEUE_FAILED_DRIVER', 'database'),
      'database' => env('DB_CONNECTION', 'mysql'),
      'table' => 'failed_jobs',
      // 必须添加该项并设为true，开启UUID自动生成
      'uuid' => true,
  ],
  

• 第二步：确认failed_jobs表结构符合默认规范，如果你手动修改过queue:failed-table生成的迁移文件，需要确保存在唯一UUID字段：
  默认迁移生成的字段规则为：

  $table->uuid('uuid')->unique();
  

  如果你的表中该字段被改为自增整型、或者缺失唯一约束，备份数据后回滚迁移重新生成默认表结构，执行命令：

  php artisan migrate:rollback --path=database/migrations/xxxx_xx_xx_xxxxxx_create_failed_jobs_table.php
  php artisan queue:failed-table
  php artisan migrate
  

• 第三步：清除配置缓存并重启队列进程
  修改配置后必须执行以下操作让配置生效：
  1. 清除配置缓存：php artisan config:cache
  2. 重启Supervisor管理的所有队列工作进程，常驻进程不会自动读取新的配置。
• 第四步：功能验证
  可以创建测试任务快速验证效果：

  // 测试任务类
  class TestFailedJob implements ShouldQueue
  {
      use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
  
      public function handle()
      {
          // 直接抛出异常触发失败
          throw new \Exception('测试队列失败写入');
      }
  }
  

  派发任务后等待队列执行，检查failed_jobs表是否有正常写入记录、UUID字段自动生成了有效值。

特殊场景排查 #

如果配置全部正确还是无法生成UUID，检查是否在任务类的failed()方法中重写了默认的失败记录写入逻辑，如果你自定义了失败存储逻辑，需要手动生成UUID写入，可以用(string) Str::uuid()生成符合规范的UUID值。

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