直接用 Mail 门面发邮件会阻塞请求，因其同步调用 SMTP 导致网络延迟时 HTTP 请求卡住；应将邮件构造与发送逻辑封装为队列任务，通过 Queue::push 投递可序列化数据，并由常驻进程执行。
为什么直接用 think\facade\Mail 发邮件会阻塞请求
ThinkPHP 默认的 Mail 门面是同步调用 SMTP 协议发信的，一旦网络延迟高、邮箱服务商响应慢（比如腾讯企业邮箱偶发 3–5 秒超时），整个 HTTP 请求就会卡住，用户看到白屏或超时错误。这不是代码写得不对，而是设计上没做解耦。
真正该走队列的，不是“发邮件”这个动作本身，而是“构造邮件内容 + 调用发送逻辑”这个过程。所以核心不是替换 Mail::send()，而是把它塞进队列任务里执行。
- 别在控制器里直接调
Mail::send()，哪怕加了 try-catch 也拦不住阻塞 - 队列驱动必须选支持持久化的，
database或redis，别用sync（那根本不算队列） - 确保队列消费者进程常驻运行，比如用
php think queue:listen或 Supervisor 管理
如何定义一个可序列化的邮件队列任务
ThinkPHP 的队列任务类必须实现 think\queue\Job 接口，且所有参数必须能被 PHP 序列化。别传 Closure、Resource、Db 连接实例这类东西——常见坑是把 $user 对象整个传进去，结果反序列化失败报 unserialize(): Error at offset。
正确做法是只传必要 ID 和原始数据：
立即学习“PHP免费学习笔记（深入）”；
namespace app\job;
use think\queue\Job;
use think\facade\Mail;
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，否则重试机制会反复执行
\think\Log::error('SendEmailJob failed: ' . $e->getMessage());
$job->delete(); // 失败就删掉，避免无限重试
return;
}
$job->delete(); // 成功后手动删除
}
}
- 别在
fire()里 new Model 或调Db::，需要查库的话，把 ID 传进来再查 - 如果邮件模板复杂，建议提前渲染成 HTML 字符串再传入，而不是在队列里调
view()->fetch() -
$job->delete()必须显式调用，否则任务会一直留在队列里（除非配置了自动删除）
怎样从控制器安全投递邮件任务
投递动作本身要轻量，不能依赖当前请求上下文（比如 input()、session()）。所有数据必须在投递前准备好并转为数组。
示例：用户注册后发欢迎邮件
// 控制器里
use think\facade\Queue;
$data = [
'to' => $user['email'],
'subject' => '欢迎注册',
'body' => view('email/welcome', ['name' => $user['name']])->render(),
];
Queue::push('app\job\SendEmailJob', $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 临时不可用的情况下不崩、不丢、可追溯。真正的难点从来不是“怎么投递”，而是“怎么确认它真发出去了”。
