本文详解 Laravel 队列的正确配置流程，涵盖驱动选择、表迁移、进程启动、常见陷阱（如 .env 中误填数据库名）及任务分发验证方法，助你快速定位“任务不入队/不执行”问题。
本文详解 laravel 队列的正确配置流程，涵盖驱动选择、表迁移、进程启动、常见陷阱（如 `.env` 中误填数据库名）及任务分发验证方法，助你快速定位“任务不入队/不执行”问题。
在 Laravel 中启用真正异步的队列处理，绝非仅靠 ShouldQueue 接口或 dispatch() 方法即可自动生效——它是一套需严格对齐的配置闭环。你遇到的「任务不入 jobs 表、queue:work 无日志、queue:listen 无响应」现象，90% 源于队列连接配置错误，正如答案所指出：.env 中 QUEUE_CONNECTION=database_name 是典型误用。
✅ 正确配置队列驱动（关键第一步）
QUEUE_CONNECTION 的值 不是数据库名，而是 Laravel 内置的驱动标识符（如 database、redis、sqs）。它指向 config/queue.php 中 connections 数组下的键名：
# ❌ 错误：database_name 是你的 MySQL 数据库名，不是队列驱动名 QUEUE_CONNECTION=database_name # ✅ 正确：使用 Laravel 官方支持的驱动标识 QUEUE_CONNECTION=database # 或 QUEUE_CONNECTION=redis
确认 config/queue.php 中存在对应驱动配置（默认已内置）：
// config/queue.php
'connections' => [
'database' => [
'driver' => 'database',
'table' => 'jobs',
'queue' => 'default',
'retry_after' => 90,
'after_commit' => false,
],
'redis' => [
'driver' => 'redis',
'connection' => 'default', // 对应 config/database.php 中 redis.default
'queue' => 'default',
'retry_after' => 90,
'block_for' => null,
'after_commit' => false,
],
],
⚠️ 注意：若选用 redis，请确保 composer require predis/predis:^1.0 已安装，且 REDIS_HOST、REDIS_PORT 等环境变量与 config/database.php 中 redis.default 配置完全一致，否则 queue:work 启动时会直接报 Connection refused。
✅ 生成并运行队列表迁移
使用 database 驱动必须创建 jobs 表（存储待执行任务）和 failed_jobs 表（记录失败任务）：
# 1. 生成 jobs 表迁移文件 php artisan queue:table # 2. 生成 failed_jobs 表迁移文件（强烈建议，便于排查） php artisan queue:failed-table # 3. 执行所有迁移 php artisan migrate
此时检查数据库，应能看到 jobs 和 failed_jobs 两张空表。若表未创建，请检查 database/migrations/ 下是否生成了对应迁移文件（如 2026_05_15_000000_create_jobs_table.php），再运行 migrate。
PHP中文网提供Laravel 13.2.0版本下载，Laravel框架 是基于 PHP 8.3+ 的高性能框架，官方推荐通过 Composer 安装。它内置 AI SDK、JSON:API Resources 及原生向量搜索，支持属性驱动开发与队列路由，大幅提升开发效率。相比旧版，13.2.0 优化了缓存 TTL 管理与实时通信，无需 Redis 即可横向扩展。作为现代 Web 开发首选，它兼顾安全与极速体验，助您快速构建企业级应用。
✅ 正确分发任务并验证入队
你的控制器代码逻辑正确，但需确保在队列驱动配置生效后再调用：
// App/Http/Controllers/TestController.php
use App\Jobs\CheckSuscription;
public function index()
{
// ✅ 正确：任务将被推送到 'processing' 队列（需 config/queue.php 中 database 驱动的 queue 值为 'processing'，或显式指定）
CheckSuscription::dispatch()->onQueue('processing');
// ? 调试建议：返回响应前打印日志，确认 dispatch 被执行
\Log::info('CheckSuscription job dispatched to processing queue.');
return response()->json(['status' => 'dispatched']);
}
✅ 验证是否成功入队：
访问该路由后，立即查询数据库：
SELECT * FROM jobs WHERE queue = 'processing' ORDER BY id DESC LIMIT 5;
若看到新记录（job 字段为序列化任务数据，attempts 为 0），说明任务已成功写入队列；若为空，则问题仍在配置或分发环节。
✅ 启动监听器并观察执行
-
开发调试时，使用带详细日志的单次监听：
php artisan queue:work --queue=processing --verbose --delay=1 --memory=128
✅ 此命令会实时输出 Processing, Processed, Failed 等日志。若仍无任何输出，说明监听器未连接到正确驱动（再次核对 QUEUE_CONNECTION 和 --queue 参数是否匹配）。
-
生产环境务必使用 Supervisor 守护进程，避免终端关闭导致中断：
# /etc/supervisor/conf.d/laravel-worker.conf [program:laravel-worker] process_name=%(program_name)s_%(process_num)02d command=php /var/www/your-app/artisan queue:work --queue=processing --sleep=3 --tries=3 --max-time=3600 autostart=true autorestart=true user=www-data numprocs=2 redirect_stderr=true stdout_logfile=/var/log/laravel-worker.log
? 常见致命错误与解决方案
| 现象 | 原因 | 解决方案 |
|---|---|---|
| jobs 表始终为空 | QUEUE_CONNECTION 值错误（如 database_name）、或未重启应用缓存 | 改为 database，执行 php artisan config:clear |
| queue:work 启动报 Connection refused（Redis） | REDIS_* 环境变量与 config/database.php 不一致 | 运行 php artisan tinker → config('database.redis.default') 验证连接参数 |
| 任务入队但不执行 | 监听器未指定对应队列（如任务发往 processing，但 queue:work 未加 --queue=processing） | 显式指定队列：php artisan queue:work --queue=processing |
| 代码修改后任务仍执行旧逻辑 | queue:work 是常驻进程，不自动重载代码 | 部署时执行 php artisan queue:restart，或杀掉进程后重启 |
✅ 最终验证：端到端成功链路
- .env: QUEUE_CONNECTION=database
- 数据库：jobs 和 failed_jobs 表存在且可写
- 控制器：CheckSuscription::dispatch()->onQueue('processing') 被调用
- 终端：php artisan queue:work --queue=processing --verbose 启动后，立即看到 Processing job... 日志
- 数据库：ProfessorSuscriptionHistory 表中新增一条 user_id=13 的记录
完成以上五步，即标志 Laravel 队列已健康运行。记住：队列不是“设好就跑”，而是“配准、建表、发任务、启监听、看日志、查结果”的严谨闭环。任何一环错位，都会导致静默失败——而这正是你最初问题的根源。
