跳转到主要内容
设计队列任务的重试时,要把”尝试几次""尝试到什么时候""允许多少次异常""到下一次尝试等待几秒”分开考虑。在 Laravel 13 中,这些都可以通过任务的 Attribute 和方法来声明。
本页面向 Laravel 13 和 Framework v13.42.0。内容不是队列的基本用法,而是重试设置的组合方式与优先级。

区分尝试次数和重试期限

Laravel 的”尝试”并不只是 handle() 被正常调用的次数。未处理异常、release()、WithoutOverlapping 或 RateLimited 等中间件导致的释放以及超时也会消耗尝试次数。如果什么都不指定,worker 只会尝试任务一次。

Tries:为次数设置上限

可以用 Tries Attribute 声明每个任务的上限。任务上的指定优先于 worker 的 --tries。
如果要根据运行时条件决定上限,请使用 tries() 方法。该方法优先于 Tries Attribute。

RetryFor:指定时间窗口

如果不按次数,而是按投递到队列后可重试的时间来限制,请使用 RetryFor。不带名称的位置参数表示秒数,也可以用命名参数指定 minutes 和 hours。
以下指定分别表示秒、分钟和小时。
RetryFor 会把重试期限记录在任务的负载中。worker 不会再启动已超过期限的任务。如果任务有 retryUntil() 方法或 retryUntil 属性,则它们优先于 RetryFor。另外,对于 retryUntil 生效的任务,基于时间的期限优先于 Tries。
retryUntil() 适合根据任务内容动态决定期限的场景,例如外部服务的恢复时间或业务截止时间。

决定未处理异常的上限

有时你希望继续允许手动 release() 或等待获取锁时的释放,但在未处理异常持续发生时尽早失败。这种情况下,请分别指定 Tries 和 MaxExceptions。
在这个例子中,任务最多可以尝试 25 次。但如果未处理异常发生 3 次,即使尚未达到尝试次数上限也会失败。MaxExceptions 并不是用来统计 release() 导致的重试次数的设置。 默认情况下,进程因内存不足等原因崩溃的尝试不计入 MaxExceptions 的异常数。如果崩溃也需要算作异常,请添加 CountCrashesAsExceptions。

设置重试间隔

发生异常的任务通常会被重新释放回队列。到下一次尝试的等待时间可以通过 Backoff Attribute 或 backoff() 方法设置。

固定间隔

指定数组时,可以为每次尝试设置不同的间隔。数组元素用完后会使用最后一个值。
如果要根据条件改变间隔,请使用 backoff()。backoff() 优先于 Backoff Attribute。
任务没有指定时,会使用 worker 的 --backoff。

以相同的退避释放等待中的任务

当外部 API 返回”处理中”等情况下,如果想不抛出异常而稍后再次执行任务,请使用 releaseUsingBackoff()。它会使用任务所设置的退避数组中与当前尝试对应的值来释放任务。值用完后使用最后一个值,没有退避时立即释放。
异常时的自动释放与通过 releaseUsingBackoff() 的手动释放,目的不同。
  • 异常时:任务未能处理,因此 Laravel 使用退避来释放。
  • 手动释放:处理本身正常,但要等外部状态变化后再稍后执行。
releaseUsingBackoff() 的等待时间参照任务的 Backoff 或 backoff()。如果想在手动释放时明确指定其他等待时间,请使用 release(秒数)。

组合示例

下面的任务最多重试 1 小时,最多允许 3 次未处理异常。在异常时或等待支付的手动释放中,使用 10 秒、30 秒、60 秒的间隔。
存在 RetryFor 时,worker 会以期限而不是 Tries(25) 作为常规的尝试上限。如果两者都指定,请决定以基于时间的期限为主,还是以基于次数的上限为主,并用测试固定这一意图。MaxExceptions 独立于两者生效。

设置的优先级

混合使用任务和 worker 的设置时,按以下优先级考虑会更容易判断。 存在由 retryUntil 或 RetryFor 设定的期限时,worker 会优先于 tries 的次数考虑期限。同时使用 RetryFor 和 retryUntil() 时,动态的 retryUntil() 优先。

如何选择

  • 等待外部服务恢复的期限明确时用 RetryFor,期限在运行时才确定时用 retryUntil()。
  • API 的速率限制或支付状态的确认,使用 Backoff 和 releaseUsingBackoff()。
  • 想大量允许临时的锁等待、同时减少实际异常时,组合使用 Tries 和 MaxExceptions。
  • 对于重试会叠加副作用的处理,不仅要设计尝试次数,还要设计幂等性以及外部 API 侧的重复控制。
Tries 和 RetryFor 也可以指定在进入队列的事件监听器和通知上。请确认所使用对象的负载具有相同的重试约定。

参考链接

最后修改于 2026年11月16日