Hyperf 3.0 异步队列消费者由主进程自动调度,启动需确保四步闭环:① async_queue.php 中 'processes' > 0 且 driver 配置有效;② processes.php 注册 ConsumerProcess 或自定义带 #[Process] 的子类;③ 消费者类实现 isEnable() 返回 true,并按驱动补全必要属性;④ 启动后日志显示 Process[xxx] start 且 ps 命令验证进程数量匹配。

Hyperf 3.0 中异步队列消费者进程不是靠手动启停脚本维持,而是由主服务进程统一调度、自动拉起与回收;若消费者未运行、秒退或数量不符,问题一定出在配置闭环未打通或进程注册未生效。
确认 async_queue.php 中进程开关已打开
打开 config/autoload/async_queue.php,找到 default 配置块,检查 'processes' 键值是否为大于 0 的整数,例如 'processes' => 1。这个值必须显式设置,不能留空或注释掉——【processes=0 时 ConsumerProcess 根本不会被创建,这是最常导致“消费者没启动”的原因】。
同时确认 'driver' 指向有效的驱动类,如 Hyperf\AsyncQueue\Driver\RedisDriver::class,并且该驱动所依赖的 Redis 连接池(如 'redis.pool' => 'default')已在 config/autoload/databases.php 或 config/autoload/redis.php 中正确定义。
验证 ConsumerProcess 是否已注册进 processes.php
打开 config/autoload/processes.php,确认文件返回数组中包含 Hyperf\AsyncQueue\Process\ConsumerProcess::class。
如果使用自定义消费者类(如 App\Process\AsyncQueueConsumer),需确保该类存在、继承 ConsumerProcess、并正确添加 #[Process] 注解;此时 config/autoload/processes.php 中反而不能重复写入 Hyperf\AsyncQueue\Process\ConsumerProcess::class,否则会启动两个同名进程造成冲突。
检查消费者类是否满足启用条件
Hyperf 不会无条件加载所有带 #[Process] 的类,必须满足以下全部条件:
① 类必须实现 public function isEnable(): bool 方法,且返回 true;
② 若使用 Redis 驱动,无需额外属性;若使用 AMQP 驱动,则必须声明 public string $exchange、public string $routingKey、public string $queue 三个属性;
③ 类文件路径必须能被 Composer 自动加载(即在 composer.json 的 autoload → psr-4 中映射正确)。
缺一不可,任意一条不满足,进程列表里就看不到它。
启动服务并观察进程日志
执行 php bin/hyperf.php start 启动服务。
启动过程中,控制台应立即输出类似 Process[ConsumerProcess] start 或 Process[AsyncQueueConsumer] start 的日志行——没有这行,说明注册失败或 isEnable() 返回 false。
若看到 Process[ConsumerProcess] abnormal exit 或反复重启,大概率是 Redis 连接池未就绪(检查 redis.php 配置)、或 Redis 服务本身不可达(telnet host port 测试)。
实时验证进程是否真实运行
服务启动后,执行 ps aux | grep "ConsumerProcess" 或 ps aux | grep "AsyncQueueConsumer"。
输出结果中应有且仅有与 async_queue.php 中 'processes' 值相等数量的进程,且 CMD 列显示为 /usr/bin/php bin/hyperf.php start。
若数量为 0,回看前四步;若数量正确但任务不消费,说明 Job 投递失败或 handle() 方法抛出未捕获异常导致进程退出——此时需查日志而非进程列表。


















