队列未执行的主因是默认使用sync驱动导致任务即时执行而非入队，须改queue_connection为redis等异步驱动并重启queue:work；dispatch()链式调用delay()和onqueue()必须前置且仅对shouldqueue接口有效；生产环境需用supervisor守护，避免进程中断；job构造函数只传id等标量，禁止i/o操作。
队列没跑起来，八成是 QUEUE_CONNECTION 还卡在 sync；任务进了队列但不执行，大概率是 queue:work 没在运行，或 Supervisor 配置漏了重启逻辑。
为什么 dispatch() 看似调用了却没进队列
这不是代码写错了，而是 Laravel 默认走 sync 驱动——它根本不会存任务，而是立刻执行 handle()。这在开发初期极易误判为“队列生效了”，实则完全绕过了异步流程。
- 检查
config('queue.default')或直接看.env：必须是redis、database等非sync值 -
sync是合法驱动，专用于本地调试（比如想单步跟handle()），不是配置失效的信号 - 改完
.env后，务必重启队列监听器（queue:work不会自动重载配置） - 数据库驱动下，若漏掉
php artisan queue:table && php artisan migrate，任务会静默失败，日志里只报 SQL 错误
delay() 和 onQueue() 不生效的典型写法陷阱
这两个方法必须链在 dispatch() 调用的最前端，且仅对实现 ShouldQueue 接口的 Job 类有效。一旦顺序错位或对象类型不对，就退化为普通方法调用，毫无队列语义。
- 错误写法：
MyJob::dispatch($id)->delay(...)——dispatch()已触发构造与序列化，delay()失去控制权 - 正确写法：
MyJob::dispatch($id)->delay(now()->addMinutes(5))->onQueue('high') -
delay()参数只能是\DateTimeInterface或整数秒（如300），不能传字符串'5 minutes' -
onQueue('high')指定的是队列名（Redis 中的 list key 名），不是连接名；连接由QUEUE_CONNECTION决定
生产环境 queue:work 必须被守护，否则等于没配
手动敲 php artisan queue:work 只适合调试。终端关闭、SSH 断连、部署重启都会让进程消失，任务积压无感知。
- Supervisor 是 Linux 生产环境事实标准：需配置
autostart=true、autorestart=true、stopasgroup=true（避免子进程残留） - 不要用
nohup &或screen：无健康检查、无日志轮转、崩溃后不自愈 - 多个队列可分优先级启动：
php artisan queue:work --queue=high,default，但注意high队列里的任务会持续抢占，default可能长期饥饿 - Redis 驱动下，若未设
retry_after（默认 90 秒），长时间运行的任务可能被重复消费
Job 类里传对象还是传 ID？这是性能和稳定性的分水岭
构造函数里传完整 Eloquent 模型或 Request 对象，看似方便，实则埋下序列化失败、数据过期、内存溢出三重隐患。
- 永远只传标量：ID、字符串、数字。在
handle()中再用User::find($this->userId)查一次 - 模型支持延迟加载（
SerializesModelstrait），但前提是构造时只传 ID；传整个模型会导致闭包、资源句柄等无法序列化的属性被捕获 - 若必须传复杂结构，确保类实现了
__serialize()/__unserialize()，或改用 DTO + JSON 编码 - 构造函数里禁止任何 I/O 操作（DB 查询、HTTP 调用），所有耗时逻辑严格收口到
handle()
最常被跳过的其实是 retry_after 和 maxExceptions 这类配置项——它们不写在 Job 类里，而藏在 config/queue.php 的连接定义中。一个超时未完成的任务，可能被 Redis 重复塞进队列三次，而你只在日志里看到一句 “Job failed after 3 attempts”。
