Laravel 7基于队列与Jobs批量发邮件仅送达单封的问题排查

• 单Job内通过foreach循环逐封发送邮件的逻辑技术上可行但并非最佳实践：
  • 劣势：收件人数量较多时，单个Job执行时间过长，容易触发队列超时限制；循环中某一封邮件发送失败抛出异常时，整个Job会被重试，导致已成功发送的邮件重复发送。
  • 更优方案：将每封邮件封装为独立的可队列化Mailable类，逐个派发任务，避免单个Job承载过多逻辑。

你遇到的收件人格式异常、仅成功发送1封邮件的问题，核心原因如下：

• Message对象复用导致收件人累加：Laravel 5.x及更早版本中，Mail外观的底层Message实例在同一进程生命周期内可能被复用，循环中多次调用$message->to($email)时，会将新收件人追加到原有列表中而非覆盖，最终出现"test2@gmail.com" <test1@gmail.com>这类异常收件人格式（本质是邮件头的收件人数组未被清空）。
• Job handle方法存在多余参数：队列Job的handle方法由队列worker的CLI进程调用，不应传入Request $request参数：CLI模式下不存在HTTP请求的Request对象，Laravel会解析空Request实例，可能导致意外逻辑异常。
• Job未实现ShouldQueue接口：如果SendQueueEmail类未实现Illuminate\Contracts\Queue\ShouldQueue接口，dispatch($job)会同步执行Job逻辑，而非推入队列异步运行，既会阻塞HTTP请求，也无法触发队列的异常重试机制。
• SMTP连接中断：循环中连续发送多封邮件时，若未主动重置连接，可能出现SMTP认证失效、超时等问题，导致第二封邮件发送失败、循环中断。

1. 修正Job基础结构 #

移除handle方法的多余参数，确保Job类实现ShouldQueue接口：

// 引入队列接口
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Bus\Queueable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Queue\InteractsWithQueue;

class SendQueueEmail implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    // 保留原有构造函数
    public function __construct($body, $titleName)
    {
        $this->body = $body;
        $this->titleName = $titleName;
    }

    // 移除handle方法的Request参数
    public function handle()
    {
        // 原有业务逻辑
    }
}

2. 优化邮件发送逻辑，避免Message复用 #

方案A（快速兼容旧版本）：循环发送时手动清空收件人列表 #

foreach ($emailsAlumni as $email) {
    Mail::send('main.admin.email.general', $data, function ($message) use ($email) {
        // 先清空原有收件人列表，避免累加
        $message->getSymfonyMessage()->setTo([]);
        $message->to($email);
        // 复用控制器传入的标题，替换原有写死的'title'
        $message->subject($this->titleName);
    });
}

方案B（推荐长期使用）：使用可队列化Mailable类 #

1. 生成Mailable类：
   php artisan make:mail GeneralMail
2. 配置Mailable类内容：

namespace App\Mail;

use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;

class GeneralMail extends Mailable
{
    use Queueable, SerializesModels;

    public $mailData;

    public function __construct($mailData)
    {
        $this->mailData = $mailData;
    }

    public function build()
    {
        return $this->view('main.admin.email.general')
                    ->subject($this->mailData['subject']);
    }
}

3. 在Job中逐个派发邮件任务：

foreach ($emailsAlumni as $email) {
    Mail::to($email)->queue(new GeneralMail($data + ['subject' => $this->titleName]));
}

3. 配置与验证 #

• 检查.env中的SMTP配置，可适当调高config/mail.php中的timeout参数，避免发送超时。
• 修改代码后重启队列worker，确保改动生效。

注意：不要在单个Job内循环发送超过10封以上的邮件，避免单个任务执行过久阻塞队列。

内容的提问来源于stack exchange，提问作者cleopatez