Laravel队列需手动完成驱动选择、任务持久化准备和消费者进程启动三类配置,缺一则dispatch()退化为同步执行;开发用database驱动需建jobs/failed_jobs表,生产推荐redis并配好连接,必须启动queue:work或Supervisor守护进程。

Laravel安装后队列功能不能直接使用,必须手动完成三类关键配置:驱动选择、任务持久化准备、消费者进程启动。缺一不可,否则dispatch()会静默退化为同步执行。
选对队列驱动并正确配置
默认QUEUE_CONNECTION=sync,这只是调试用,不走队列。需按环境选真实驱动:
- 开发/测试环境推荐
database:在.env中设QUEUE_CONNECTION=database;再运行php artisan queue:table和php artisan queue:failed-table,最后php artisan migrate建出jobs和failed_jobs表 - 生产环境推荐
redis:确保已安装predis/predis(composer require predis/predis:^1.0),.env中设QUEUE_CONNECTION=redis,并确认config/database.php里redis.default可连、config/queue.php中redis.connection值与之匹配 - 填错驱动名(如写成
QUEUE_CONNECTION=redis_db)会导致 Laravel 自动回退到sync,无报错但任务不入队
创建可入队的任务类
用php artisan make:job SendEmail生成任务类后,还需手动操作:
- 确保类实现
ShouldQueue接口(Laravel 9+ 不自动添加,必须手写implements ShouldQueue) - 构造函数里只传可序列化的数据(如
$userId、$email),避免传Request、UploadedFile或数据库连接实例 - 若需延迟执行,不要在构造函数里计算时间,而是在分发时用
->delay(now()->addMinutes(5))
启动并守护队列工作进程
仅配置好驱动和任务类还不够,必须让 Laravel 主动拉取并执行任务:
- 本地测试可用
php artisan queue:work --verbose实时看日志;加--once只处理一个任务便于调试 - 生产环境必须用 Supervisor 管理:配置
autostart=true、autorestart=true,防止 SSH 断开或异常退出导致队列停摆 - 若没启动
queue:work,哪怕任务成功写入 Redis 或jobs表,也不会被执行
不复杂但容易忽略


















