必须正确配置并使用异步队列才能保障Hyperf高并发场景稳定运行；需安装组件、发布配置、严格匹配Redis连接池、注册消费者进程、合理调优并发与超时参数，并理解其不保证不丢消息的特性。
要让Hyperf应用在高并发下单、日志写入、消息推送等场景中不卡顿、不丢任务、不堆积，必须正确配置并使用异步队列——它不是简单装个包就能跑起来的组件，而是需要理解其消费机制、协程调度与Redis交互逻辑后才能稳住的后台引擎。
安装与基础配置
执行命令安装组件：composer require hyperf/async-queue
运行发布命令生成默认配置文件：php bin/hyperf.php vendor:publish hyperf/async-queue。该命令会把配置写入 config/autoload/async_queue.php，若手动创建请确保路径和命名完全一致，否则消费者进程启动时将静默失败。
打开配置文件，确认 【driver 必须指向 Hyperf\AsyncQueue\Driver\RedisDriver::class】，且 redis.pool 值与项目中已配置的 Redis 连接池名严格匹配（如 'pool' => 'default'），错一个字母就会导致任务投递成功但消费端永远收不到消息。
启用异步消费进程
在 config/autoload/processes.php 中添加以下行：
Hyperf\AsyncQueue\Process\ConsumerProcess::class,
这一步不可省略——Hyperf 不会自动启动消费者，必须显式注册进程。如果你用的是自定义 Consumer 类（如带注解的 AsyncQueueConsumer），请确保该类已声明 #[Process] 并在 processes.php 中引用其完整类名，而非基类。
重启服务后，通过 ps -ef | grep ConsumerProcess 可验证进程是否存活。若无输出，说明进程未加载，常见原因是配置文件路径错误或类名拼写有误。
创建并投递第一个 Job 任务
方法一：继承 Job 类（推荐用于结构清晰、需复用数据字段的场景）
在 app/Job 目录下新建 SendNotificationJob.php：
namespace App\Job; use Hyperf\AsyncQueue\Job; class SendNotificationJob extends Job { public $userId; public $content; public function __construct(int $userId, string $content) { $this->userId = $userId; $this->content = $content; } public function handle() { // 实际推送逻辑，此处仅示意 file_put_contents('/tmp/notify.log', "[{$this->userId}] {$this->content}\n", FILE_APPEND); } }
在任意 Service 或 Controller 中调用投递：
$job = new SendNotificationJob(1001, '订单已支付'); \Hyperf\AsyncQueue\Driver\RedisDriver::push($job);
方法二：使用注解方式（适合轻量、临时性任务）
在 Service 类方法上添加 #[AsyncQueueMessage] 注解，并确保该类已由 DI 容器管理（即加了 #[Inject] 或在容器中显式定义）：
#[AsyncQueueMessage] public function sendSms(string $phone, string $msg) { // 发送短信逻辑 }
调用时直接执行：$this->queueService->sendSms('13800138000', '验证码1234'); 注解方式底层自动封装为 Job 并投递，无需手动 push。
关键参数调优与故障应对
第一步：调整并发上限防止资源耗尽
在 async_queue.php 的 concurrent.limit 设置合理值，例如从默认 10 改为 【6】。过高会导致 Redis 连接打满、CPU 突增；过低则消费吞吐不足。建议按单个任务平均耗时 × 预期 QPS × 1.5 来反推，比如平均 200ms/任务、目标 30QPS，则最小需 9 个并发，再留余量设为 12。
第二步：设置处理超时避免任务卡死
将 handle_timeout 设为略大于任务最长预期执行时间（如 8 秒），一旦超过该阈值，当前协程会被强制终止，任务进入重试队列。不设或设得过大，会导致单个慢任务拖垮整个消费进程。
第三步：启用失败重试但限制最大次数
配置 retry_seconds => 3 和 max_attempts => 3。第一次失败后 3 秒重试，再失败再等 3 秒，最多尝试 3 次。超过后任务被丢弃——这是设计使然，【async-queue 不保证消息不丢失，也不提供死信队列】，业务关键任务必须自行捕获异常并落库或发告警。
