Laravel 10 中队列邮件失败无法通过全局异常处理器捕获，必须在自定义 Job 类的 failed() 方法中处理，或监听 JobFailed 事件实现全局兜底；严禁在 Handler::report() 或 Mailable 中尝试捕获。
Laravel 10 中，通过队列发送邮件（Mailable）时，失败异常不能靠全局异常处理器捕获，因为队列任务运行在独立进程（如 php artisan queue:work），与 HTTP 请求生命周期完全隔离。必须在队列任务自身或队列事件层面做针对性处理。
✅ 正确捕获邮件发送失败的两种核心方式
1. 在 Mailable 类中启用队列，并在对应 Job 类里定义 failed() 方法
Laravel 的 Mail::to()->send() 若使用了 Queueable，实际是封装成一个隐式队列任务（Illuminate\Mail\SendQueuedMailable）。但该类不支持直接重写 failed()。因此推荐显式创建自定义 Job 类来发送邮件，从而获得完整控制权：
// app/Jobs/SendWelcomeEmail.php
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\Mail;
class SendWelcomeEmail implements ShouldQueue
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
public function __construct(public $user) {}
public function handle()
{
Mail::to($this->user)->send(new WelcomeEmail($this->user));
}
public function failed(\Throwable $exception)
{
\Log::error('Welcome email failed for user '.$this->user->id, [
'exception' => $exception->getMessage(),
'trace' => $exception->getTraceAsString(),
]);
// 发送告警（如邮件、Slack、短信）
\Notification::route('mail', 'ops@example.com')
->notify(new EmailSendFailureAlert($this->user, $exception));
}
}✅ 优势：可精准记录上下文（用户 ID、异常类型）、触发差异化告警、执行清理逻辑。
2. 监听 Laravel 内置的 JobFailed 事件（全局兜底）
适用于不想修改每个 Job 类，或需统一审计/监控所有失败场景：
// app/Providers/EventServiceProvider.php → boot() 方法内
use Illuminate\Queue\Events\JobFailed;
use Illuminate\Support\Facades\Event;
Event::listen(JobFailed::class, function (JobFailed $event) {
$job = $event->job;
$exception = $event->exception;
// 过滤出邮件相关任务（可选）
if (str_contains($job->getName(), 'SendWelcomeEmail')
|| $job instanceof \Illuminate\Mail\SendQueuedMailable) {
\Log::warning('Mailable job failed', [
'job' => $job->getName(),
'exception' => $exception->getMessage(),
'payload' => $job->payload(),
]);
// 统一告警通道
\Mail::to('alert@yourapp.com')->send(
new QueueJobFailureReport($job, $exception)
);
}
});⚠️ 注意：SendQueuedMailable 的 payload 中包含 mailable 类名和收件人信息，可从中提取关键字段用于诊断。
❌ 常见误区（务必避免）
在
App\Exceptions\Handler::report()里试图捕获邮件队列异常
→ 不生效。该 Handler 只处理同步请求（Web/API）中的异常。仅用
try/catch包裹Mail::send()但未启用队列
→ 若你本意是异步发送，却误用了同步方式，会导致阻塞；若本意是队列，try/catch根本进不去。Mailable 类里加
failed()方法
→ 无效。Mailable 不实现ShouldQueue接口，failed()是 Job 类的方法。忽略 MAIL_DRIVER 配置错误（如 Gmail 未用应用专用密码）
→ 异常可能被 Guzzle 或 PHPMailer 吞掉，日志只显示 “Connection refused” 或空响应。务必检查.env和 Google 账户两步验证设置。
? 补充建议：提升可观测性
- 在
failed()或事件监听器中，记录job->attempts()和job->maxTries()，判断是否因重试耗尽而失败； - 对高频失败任务（如 SMTP 拒绝），添加速率限制或自动降级为“稍后重试”通知；
- 使用
php artisan queue:failed定期巡检，配合queue:retry快速恢复可修复任务。
不复杂但容易忽略。
