PHP Laravel Queue 重试 怎样处理

Laravel Queue 重试不要简单设置一个很大的次数。更稳妥的做法是：用 worker 的 --tries 或任务类的 $tries 限制尝试次数，用 $backoff 或 --backoff 拉开瞬时故障的间隔；如果任务只能在某个时间窗口内继续处理，再用 retryUntil() 截止。超过边界后让任务进入失败记录，修复根因后再通过 queue:retry 有选择地回放。

官方地址：https://laravel.com/docs/queues

先把重试次数和重试时间分开

Laravel worker 处理任务抛出异常时，会把任务重新释放回队列，直到达到允许的尝试次数。worker 可以用命令行统一设置：

# 让所有任务最多尝试 3 次，每次异常后等待 5 秒
php artisan queue:work redis --tries=3 --backoff=5

单个任务需要更细的策略时，把边界写进任务类。下面的示例让瞬时网络故障有 3 次机会，同时用时间窗口避免过期任务继续占用队列。

addMinutes(15);
    }

    public function handle(): void
    {
        // 这里应调用幂等的同步逻辑，避免重试造成重复扣款或重复写入。
        app(InvoiceSynchronizer::class)->sync($this->invoiceId);
    }

    public function failed(?\Throwable $exception): void
    {
        // 记录最终异常并通知值班人员，不要在 failed 中再次 dispatch 同一任务。
        report($exception);
    }
}

这几个配置承担不同职责：$tries 控制次数，$backoff 控制等待，retryUntil() 控制时间窗口。实际项目中还要让 handle 具备幂等性，并把任务的超时时间设在队列连接的可接受范围内。

出现失败任务时先判断是哪一层出了问题

值班时先查看失败记录，而不是马上增加 --tries。Laravel 提供了失败任务列表和重试命令：

# 查看失败任务的 ID、连接、队列和失败时间
php artisan queue:failed

# 只回放已经修复的一个任务，避免整批重复执行
php artisan queue:retry 7f3c2b1a-0000-4a00-9000-example

如果任务一直失败，重点检查四类信号：异常是否是参数或业务数据永久错误；下游接口是否只是短暂不可用；worker 的 --timeout 是否大于任务实际执行时间；队列连接的 retry_after 是否比 worker 超时更短。超时与可见重试叠加时，可能让同一任务被多个 worker 同时处理，因此部署参数要按任务最长执行时间统一设置。

处理顺序可以压缩成一句话：先保留失败记录，再修复依赖或代码；确认修复后只回放目标 ID；若数据本身不可处理，则删除或人工补偿，并在复盘中记录原因。

退避、超时和失败回放怎样配合

不要把 --tries=0 当成通用修复方案。无限重试适合极少数明确可恢复的任务，但会把故障放大为队列积压；生产任务通常应该有上限，并配合失败告警和死信处理。

上线前的运行手册清单

• 每个任务是否定义了合理的 $tries、backoff 或 retryUntil()？
• handle 重跑时是否幂等，外部请求是否带业务幂等键？
• worker 的 --timeout 是否小于队列连接的 retry_after？
• 是否能从 queue:failed 找到任务 ID、异常和依赖信息？
• 失败数量、重试成功率、最老失败任务年龄是否有告警？

这份清单的重点是让“重试”成为有边界的恢复动作，而不是让 worker 无限重复同一个错误。先固定次数和时间窗口，再根据真实失败样本调整退避，通常比一次性把参数调大更容易回滚。

常见问题

$tries 和 --tries 同时设置时看哪个？

worker 参数提供默认值，任务类可以针对单个 Job 指定更细的尝试次数。排查时把启动命令和任务类一起看，不要只改部署脚本。

失败任务修复后要不要全部重试？

不建议默认全部重试。先确认失败原因和任务是否幂等，再按任务 ID、队列或时间范围选择性回放，避免把旧数据再次提交给下游。