ThinkPHP6.0队列配置与使用教程

使用ThinkPHP6.0队列功能时，许多开发者会遇到配置后命令无响应或报错的问题。关键在于理解：ThinkPHP6.0框架自带的队列组件仅提供了接口定义，要实际使用队列，必须安装独立的扩展包。

这个核心扩展包是 topthink/think-queue。缺少它，任何队列命令都无法生效。安装命令如下：

必须安装 topthink/think-queue ^3.0 版本。ThinkPHP6.0 自带的 think\queue 仅为接口，不含驱动逻辑。配置文件位于 config/queue.php，需正确设置 default 与 connections 中的 type 值。使用 Redis 驱动需启用 php-redis 扩展。任务类必须实现 fire(Job $job, $data) 方法，并显式调用 $job->delete()。

安装与驱动准备

通过 Composer 执行安装：composer require topthink/think-queue ^3.0。请注意，ThinkPHP6.0 对应的是该扩展包的 v3.x 系列。

驱动环境准备：

• 若使用 Redis 驱动，需确保 PHP 已启用 redis 扩展，可通过命令行 php -m | grep redis 验证。
• 若使用 database 驱动，需提前创建数据表。可运行 php think migrate:run 自动迁移，或手动创建 jobs 与 failed_jobs 表。

配置文件常见问题

配置文件路径为 config/queue.php。以下配置细节容易出错：

• default 字段：其值（例如 'redis'）必须与 connections 数组中的某个键名完全一致。
• type 与 driver：在 connections 的每个连接配置中，指定驱动类型的键名是 'type'，而非 'driver'。
• Redis 参数：'select' 对应 Redis 的数据库编号；'timeout' 单位为秒，设置为 0 表示永不超时，生产环境需谨慎使用。
• 环境变量：在 queue.php 中直接使用 env('QUEUE_DRIVER') 可能无法读取 .env 文件配置，需确保环境变量已正确加载。

队列命令执行故障排查

执行 php think queue:listen 后无响应或卡住，常见原因如下：

• 队列名称不匹配：若代码中指定了队列名（如 Queue::push(..., 'mail')），则启动监听时需附带参数：php think queue:listen --queue=mail，否则仅监听 default 队列。
• Redis 连接失败：检查 host、port 连通性，密码是否正确，以及 select 指定的数据库是否存在。
• 任务类无法加载：确保任务类文件能被 Composer 自动加载。通常建议放置在 app/job/ 目录下，对应命名空间 app\job。
• 进程管理：在 Linux 服务器上建议使用 supervisor 守护队列进程；Windows 环境下直接关闭终端会导致监听进程终止。

任务类方法：fire() 与 handle()

任务类应实现的方法取决于 think-queue 的版本：

• 对于 TP6 对应的 v3.0+ 版本，任务类必须实现 fire(Job $job, $data) 方法。handle() 方法在此版本中无效。
• 任务执行成功后，必须显式调用 $job->delete() 以将任务从队列中移除，否则可能导致重复执行。
• 若需失败重试，应使用 $job->release($delay) 方法，其中 $delay 为延迟重试的秒数。

最后需注意一个易忽略的点：队列任务失败后默认无记录。若未在 config/queue.php 中配置 'failed' => ['type' => 'database'] 并创建 failed_jobs 表，失败的任务将静默消失，难以追踪。项目上线前应检查此配置。