Laravel Excel 导出队列卡住问题的解决方案

laravel excel 使用队列导出时，若仅调用 `onqueue()`，会导致主导出任务进入指定队列，但后续分片处理任务仍走默认队列，造成“卡住”假象；正确做法是使用 `allonqueue()` 确保整个导出流程（含分片、写入、上传等所有子任务）统一调度至同一自定义队列。

在 laravel 中通过 maatwebsite/excel 执行大型数据导出时，推荐启用队列以避免超时和内存溢出。但许多开发者会遇到“Horizon 显示任务已处理，却无实际文件生成、界面无响应、后续任务批量延迟触发”的现象——这并非程序崩溃，而是队列路由不一致导致的任务分散执行。

根本原因在于：->onQueue(‘exports’) 仅作用于最外层的 QueueExport 任务（即启动导出的 Job），而 Laravel Excel 在执行过程中会动态分发多个子任务（如 appendQueryToSheet, StoreExport, UploadExport 等），这些子任务默认仍发送至 .env 中配置的 QUEUE_CONNECTION=redis（或 sync/database）默认队列，而非你指定的 ‘exports’ 队列。

因此，当你只运行 php artisan horizon –wait 或仅监听 exports 队列时，主任务被消费，但子任务堆积在默认队列中无人处理，造成“卡住”错觉。

✅ 正确写法（Laravel 8+ & laravel-excel ≥3.1）：

// ✅ 正确：所有相关子任务均进入 'exports' 队列 (new OrdersExport($request))->queue('orders.xlsx')->allOnQueue('exports');  // ❌ 错误：仅 QueueExport 进入 'exports'，子任务仍走默认队列 // (new OrdersExport($request))->queue('orders.xlsx')->onQueue('exports');

? 补充最佳实践：

• 确保 Horizon 配置覆盖全部队列：检查 config/horizon.php 中 environments 下对应环境是否包含 ‘exports’ 及默认队列（如 ‘redis’）：

  'environments' => [     'production' => [         'supervisor-1' => [             'connection' => 'redis',             'queue' => ['exports', 'default', 'notifications'], // 关键：同时监听 exports 和 default             'balance' => 'auto',             'processes' => 4,         ],     ], ],

• 验证队列连接一致性：确认 .env 中 QUEUE_CONNECTION=redis（或其他支持延迟/优先级的驱动），避免使用 sync 驱动测试队列逻辑。

• 添加日志与异常捕获：在 Export 类中强化可观测性：

  public function __construct(public array $request) {}  public function query() {     Log::info('OrdersExport: Starting query with from=' . $this->request['from'] ?? 'N/A');     return Order::query()         ->when($this->request['from'] ?? null, function ($q) {             $q->whereBetween('created_at', [                 $this->request['from'],                 $this->request['to'] ?? now()             ]);         }); }  public function failed(Throwable $exception): void {     Log::error('OrdersExport FAILED: ' . $exception->getMessage(), [         'trace' => $exception->getTraceAsString(),         'request' => $this->request,     ]); }

• 本地调试技巧：若仍无法定位，临时禁用队列强制同步执行，快速验证逻辑是否正常：

  php artisan queue:work --once --verbose # 或设置 QUEUE_CONNECTION=sync 并刷新页面

总结：Laravel Excel 的队列导出是一个多阶段流水线，allOnQueue() 是保障端到端一致性的关键开关。务必配合 Horizon 多队列监听与结构化日志，才能实现稳定、可追溯的大规模导出能力。