本文详解 Laravel 队列的正确配置流程，涵盖 .env 驱动设置、数据表迁移、任务分发与监听启动，并重点解决「任务不入队、不执行、无日志」等高频问题。
本文详解 laravel 队列的正确配置流程，涵盖 `.env` 驱动设置、数据表迁移、任务分发与监听启动，并重点解决「任务不入队、不执行、无日志」等高频问题。
Laravel 队列是实现异步任务（如邮件发送、PDF 生成、订阅校验）的核心机制，但其正常运行高度依赖配置一致性与环境匹配性。你遇到的“任务不入 jobs 表、queue:work 无输出、.env 中 QUEUE_CONNECTION=database_name 失效”等问题，根源在于对 Laravel 队列抽象层的理解偏差——QUEUE_CONNECTION 的值并非数据库名，而是 预定义的连接标识符（connection name），对应 config/queue.php 中 connections 数组下的键名。
✅ 第一步：修正 .env 队列驱动配置
错误写法（常见误区）：
QUEUE_CONNECTION=database_name ← ❌ 不存在该连接，Laravel 直接降级为 sync（同步执行），且不报错
正确写法（二选一，推荐 database 开发/测试，redis 生产）：
# 开发环境轻量方案：使用 database 驱动 QUEUE_CONNECTION=database # 或生产环境高性能方案：使用 redis 驱动 # QUEUE_CONNECTION=redis
? 原理说明：config/queue.php 中默认已定义 'database' => [...] 和 'redis' => [...] 连接。QUEUE_CONNECTION 的作用是告诉 Laravel：“请使用 connections 数组中名为 database 的那一套配置”，而非指定 MySQL 数据库名。若填入未定义的名称（如 database_name），Laravel 会静默 fallback 到 sync 驱动——这正是你任务“看似调用却无任何队列表记录”的根本原因。
✅ 第二步：完成数据库驱动必备迁移（仅限 QUEUE_CONNECTION=database）
确保已执行以下三步（缺一不可）：
# 1. 生成 jobs 表迁移（存储待处理任务） php artisan queue:table # 2. 生成 failed_jobs 表迁移（存储执行失败的任务，便于重试与排查） php artisan queue:failed-table # 3. 执行迁移，创建两张表 php artisan migrate
✅ 验证：检查数据库中是否存在 jobs 和 failed_jobs 表。若无，则任务无法持久化，自然不会被 worker 拉取。
✅ 第三步：确认任务分发逻辑与队列命名一致
你的控制器代码中指定了自定义队列名：
CheckSuscription::dispatch()->onQueue('processing'); // ← 任务将进入 'processing' 队列此时，必须确保 queue:work 显式监听该队列：
# 错误：默认监听 'default' 队列，无法消费 'processing' 中的任务 php artisan queue:work # 正确：显式指定队列名 php artisan queue:work --queue=processing # 或同时监听多个队列（按优先级顺序） php artisan queue:work --queue=processing,default
⚠️ 注意：php artisan queue:listen 是旧版命令（Laravel 5.7+ 已弃用），请统一使用 queue:work。它更稳定、内存占用更低，且支持 --tries、--sleep 等关键参数。
✅ 第四步：启动并验证队列监听器
在终端中运行（开发调试用）：
php artisan queue:work --queue=processing --verbose --delay=0
- --verbose：输出详细日志，看到 Processing、Processed 等关键状态；
- --delay=0：取消失败任务重试前的等待延迟，加速验证；
- 观察终端是否打印 Processing job ... —— 若有，说明任务已成功出队并执行。
? 小技巧：为避免手动重启（代码变更后需重启 worker），可添加 --rest 参数或配合 supervisor 实现热更新：
# 优雅重启所有 worker（部署时执行） php artisan queue:restart
✅ 第五步：增强任务健壮性（可选但强烈推荐）
-
添加异常捕获与日志
在 handle() 方法中包裹逻辑，避免静默失败：public function handle() { try { $suscription_history = ProfessorSuscriptionHistory::create([ 'user_id' => 13, 'type' => 'trimestral', 'pdf' => 'test.pdf', 'ended_at' => now()->addMonths(3), ]); \Log::info("Subscription history created: {$suscription_history->id}"); } catch (\Exception $e) { \Log::error("Failed to create subscription history: " . $e->getMessage()); throw $e; // 保证失败后进入 failed_jobs 表 } } -
为队列任务指定独立数据库连接（高阶场景）
若业务要求队列操作与主库隔离（例如读写分离、避免锁表），可在 config/database.php 新增连接，并在任务中显式调用：// config/database.php 'queue_db' => [ 'driver' => 'mysql', 'host' => env('QUEUE_DB_HOST', '127.0.0.1'), // ... 其他配置 ],// Job handle() 内 ProfessorSuscriptionHistory::on('queue_db')->create([...]);
? 总结：排错清单（快速自查）
| 检查项 | 正确做法 | 常见错误 |
|---|---|---|
| ✅ .env 驱动配置 | QUEUE_CONNECTION=database | 写成 database_name、mysql、laravel_jobs 等无效值 |
| ✅ 数据表存在 | jobs + failed_jobs 表均已迁移 | 忘记 queue:failed-table 或未执行 migrate |
| ✅ Worker 监听队列 | queue:work --queue=processing | 使用默认命令，未匹配 onQueue() 指定的队列名 |
| ✅ 无 sync 陷阱 | 确保未意外启用 sync（如配置错误导致 fallback） | QUEUE_CONNECTION 值无效时 Laravel 自动回退，无提示 |
| ✅ 任务类实现接口 | implements ShouldQueue + use Queueable | 缺少 Queueable trait 导致无法序列化 |
完成以上步骤后，再次访问 TestController@index，你会在 jobs 表中看到新记录，在终端看到 Processing 日志，最终在 professor_suscription_histories 表中查到插入的数据——Laravel 队列即宣告打通。记住：队列不是“开箱即用”，而是“配置即契约”。严格遵循连接名约定、队列表完整性、监听队列匹配这三大原则，90% 的队列失效问题都将迎刃而解。
