怎样在ThinkPHP中实现邮件队列异步发送【扩展】

直接用 Mail 门面发邮件会阻塞请求，因其同步调用 SMTP 导致网络延迟时 HTTP 请求卡住；应将邮件构造与发送逻辑封装为队列任务，通过 Queue::push 投递可序列化数据，并由常驻进程执行。

为什么直接用 thinkfacadeMail 发邮件会阻塞请求

ThinkPHP 默认的 Mail 门面是同步调用 SMTP 协议发信的，一旦网络延迟高、邮箱服务商响应慢（比如腾讯企业邮箱偶发 3–5 秒超时），整个 HTTP 请求就会卡住，用户看到白屏或超时错误。这不是代码写得不对，而是设计上没做解耦。

真正该走队列的，不是“发邮件”这个动作本身，而是“构造邮件内容 + 调用发送逻辑”这个过程。所以核心不是替换 Mail::send()，而是把它塞进队列任务里执行。

• 别在控制器里直接调 Mail::send()，哪怕加了 try-catch 也拦不住阻塞
• 队列驱动必须选支持持久化的，database 或 redis，别用 sync（那根本不算队列）
• 确保队列消费者进程常驻运行，比如用 php think queue:listen 或 Supervisor 管理

如何定义一个可序列化的邮件队列任务

ThinkPHP 的队列任务类必须实现 thinkqueueJob 接口，且所有参数必须能被 PHP 序列化。别传 Closure、Resource、Db 连接实例这类东西——常见坑是把 $user 对象整个传进去，结果反序列化失败报 unserialize(): Error at offset。

正确做法是只传必要 ID 和原始数据：

立即学习“PHP免费学习笔记（深入）”；

namespace appjob;

use thinkqueueJob;
use thinkfacadeMail;

class SendEmailJob
{
    public function fire(Job $job, $data)
    {
        // $data 是你投递时传入的数组，例如 ['to' => 'a@b.com', 'subject' => '...', 'body' => '...']
        try {
            Mail::to($data['to'])
                ->subject($data['subject'])
                ->html($data['body'])
                ->send();
        } catch (Exception $e) {
            // 记录日志，但别 throw，否则重试机制会反复执行
            thinkLog::error('SendEmailJob failed: ' . $e->getMessage());
            $job->delete(); // 失败就删掉，避免无限重试
            return;
        }

        $job->delete(); // 成功后手动删除
    }
}

• 别在 fire() 里 new Model 或调 Db::，需要查库的话，把 ID 传进来再查
• 如果邮件模板复杂，建议提前渲染成 HTML 字符串再传入，而不是在队列里调 view()->fetch()
• $job->delete() 必须显式调用，否则任务会一直留在队列里（除非配置了自动删除）

怎样从控制器安全投递邮件任务

投递动作本身要轻量，不能依赖当前请求上下文（比如 input()、session()）。所有数据必须在投递前准备好并转为数组。

示例：用户注册后发欢迎邮件

// 控制器里
use thinkfacadeQueue;

$data = [
    'to'      => $user['email'],
    'subject' => '欢迎注册',
    'body'    => view('email/welcome', ['name' => $user['name']])->render(),
];

Queue::push('appjobSendEmailJob', $data);

• 别写 Queue::push(..., $this) 或 Queue::push(..., $request)，会序列化失败
• 如果用了 Redis 驱动，确保 queue.php 中 'default' => 'redis'，且 redis 配置项正确
• 开发环境测试时，可用 php think queue:work --once 手动触发一次，比 listen 更易调试

SMTP 配置和超时问题怎么避坑

队列里发信失败，90% 是 SMTP 连接超时或认证失败，但错误不会直接抛到页面上，只会静默失败或写进日志。必须主动监控。

• 在 config/mail.php 中设 'timeout' => 10，别用默认的 30 秒，避免任务卡死
• 开启 SMTP debug 模式：'debug' => true，但仅限开发环境，生产环境关掉，否则日志爆炸
• 腾讯企业邮箱需用 ssl://smtp.exmail.qq.com:465，网易用 tls://smtp.163.com:587，协议+端口错一个就连不上
• 密码别写明文，用环境变量：'password' => env('MAIL_PASSWORD', '')

队列任务的健壮性不取决于代码多漂亮，而在于它能否在各种网络抖动、SMTP 临时不可用的情况下不崩、不丢、可追溯。真正的难点从来不是“怎么投递”，而是“怎么确认它真发出去了”。