ThinkPHP8.1分布式队列防重复消费需四层防护：①用ShouldBeUnique入队去重；②手动提交位移+延长retry_after；③业务层Cache::add原子幂等校验；④数据库唯一索引兜底。

ThinkPHP8.1在分布式部署下，多个队列消费者实例共用同一套Redis（或数据库）驱动时，天然面临重复消费风险。这不是框架缺陷，而是“至少一次”投递语义与网络、重启、重平衡等现实因素共同作用的结果。防重复的关键不在于阻止消息被多次分发，而在于确保同一业务逻辑无论被执行几次，结果都一致——也就是落地业务幂等。

用think-queue的ShouldBeUnique机制入队去重

ThinkPHP8.1+配合think-queue 3.x支持原生去重能力，核心是在任务入队前就拦截重复：

• 让任务类实现ShouldBeUnique接口，框架会自动生成唯一指纹（默认为类名+序列化属性值）
• 通过uniqueId()方法自定义业务维度去重键，例如：return 'cancel_order_' . $this->orderNo;
• 用uniqueFor(900)设置去重窗口为15分钟，覆盖订单自动取消这类场景的合理时间范围
• 该机制依赖Redis原子命令（如SETNX），必须确保Redis连接正常且驱动配置正确（非sync模式）

手动提交位移 + 关闭自动确认

think-queue默认使用自动ACK，一旦任务被取出即标记为已消费，但若处理中途崩溃，就会丢失位移信息，导致消息重放。应改为手动控制：

PHP 8.5.12

修复 Core bailout 状态损坏安全问题，以及 BZ2、DOM、PDO、Opcache/JIT 内存与执行错误，改进 Unicode 字素处理、URL 解析、TLS 流状态、信号分发及会话错误处理。

下载

• 在config/queue.php中将'retry_after'设为足够长的值（如600秒），避免因耗时操作误判超时
• 消费者启动时加--timeout=595参数，留出缓冲防止进程僵死
• 在Job的handle()末尾显式调用$this->job->delete()（仅适用于Redis驱动），或通过事务+状态更新完成“处理完成即确认”的语义

业务层加幂等校验兜底

ShouldBeUnique只能防“同参数任务重复入队”，无法覆盖网络抖动、手动重试、消费者实例重启后重新拉取等场景。必须在业务逻辑内做第二道防线：

立即学习“PHP免费学习笔记（深入）”；

• 在handle()开头生成强业务唯一键，如'idempotent:cancel_order_' . $this->orderNo
• 用Cache::add($key, true, 600)原子写入Redis，返回false说明已被其他实例抢占，直接return
• TTL建议设为预估最大执行时间×1.2，比如取消订单预计耗时8秒，TTL设为10秒更稳妥
• 禁止使用Cache::has() + Cache::put()组合，非原子操作会导致竞态条件

数据库唯一约束作为最终防线

对写库类操作（如插入订单记录、扣减库存流水），直接在数据库表上建唯一索引是最可靠兜底：

• 例如订单取消任务需写order_log表，则给(order_no, action_type)建联合唯一索引
• 代码中捕获Illuminate\Database\QueryException中包含“Duplicate entry”的异常，视为幂等成功
• 这种方案不依赖中间件稳定性，即使Redis宕机、缓存穿透，也能靠数据库拦住脏数据