Laravel10 邮件 Mail 发送队列邮件，邮件发送失败捕获异常方法-php教程-PHP中文网

laravel 10 中队列邮件失败无法通过全局异常处理器捕获，必须在自定义 job 类的 failed() 方法中处理，或监听 jobfailed 事件实现全局兜底；严禁在 handler::report() 或 mailable 中尝试捕获。

laravel10 邮件 mail 发送队列邮件，邮件发送失败捕获异常方法

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、异常类型）、触发差异化告警、执行清理逻辑。

Laravel Creem Agent

Creem 支付商店助理 — 查询订阅、客户、交易、产品，执行心跳检查，管理本地 Laravel支付商店。

下载

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 账户两步验证设置。