x-delayed-message插件是RabbitMQ实现延迟消息的最成熟方案，原生AMQP不支持延迟队列；必须启用插件、声明x-delayed-message类型交换机并设置x-delayed-type参数，否则静默失败。
延迟消息必须用 x-delayed-message 插件，原生 AMQP 不支持
RabbitMQ 本身不提供延迟队列能力，x-delayed-message 是最成熟、生产验证过的插件方案。Koa2 应用里若直接用 publish 发送带 expiration 的消息，只会让消息在队列里过期丢弃，**不会延迟投递**——这是新手最常踩的坑。
必须先启用插件：
docker exec -it rabbitmq rabbitmq-plugins enable rabbitmq_delayed_message_exchange（Docker 部署）或通过管理界面确认插件已激活。未启用时发消息会静默失败，连错误都不抛，只在 RabbitMQ 日志里留一句
unknown exchange type 'x-delayed-message'。
Exchange 类型必须设为 x-delayed-message，且声明时要显式传入 arguments: { 'x-delayed-type': 'direct' }，否则后续绑定会报错。
Koa2 中封装 publish 延迟发送逻辑要隔离 connection 和 channel
不能每次发短信都新建 amqplib.connect()，也不能复用未做错误监听的 channel。RabbitMQ 连接断开后，channel 会进入 close 状态，再调 publish 就卡住或抛 Channel closed 错误。
推荐做法是：
- 用单例管理
connection，监听close和error事件并触发重连 - 每次发消息前用
connection.createChannel()新建channel，用完立刻channel.close() - 延迟时间单位是毫秒，不是秒——
msg.delay = 60 * 1000表示 1 分钟后发，写成60就变成 60 毫秒 - 消息体必须是
Buffer，JSON.stringify({ phone: '138...', content: '...' })后要用Buffer.from(...)包一层
消费端处理短信任务需手动 ack + 幂等控制
短信服务不可重试，但 RabbitMQ 默认 autoAck = false，如果没调 channel.ack(msg)，消息会一直卡在 unacked 状态，下次消费者重启还会重复拉取。
RabbitMQ 4.2.3 是 2026 年初发布的重要稳定更新版本，重点修复了 Khepri 元数据存储相关问题，并改进了监控性能。对于使用 Docker、Kubernetes 或微服务架构的开发团队来说，该版本兼容性和稳定性表现较好。
更关键的是：延迟消息可能因网络抖动、服务重启等原因被重复投递。必须在消费逻辑里加幂等判断，比如：
- 用 Redis 记录
task_id+EXPIRE 10m，消费前先SETNX校验 - 数据库表加唯一索引（如
phone + send_time_truncated_to_minute），插入失败即跳过 - 不要依赖消息 ID 做幂等——RabbitMQ 不保证消息 ID 全局唯一
另外，消费端抛出异常时，别直接 channel.nack(msg, false, true) 重入队列，否则可能无限循环。建议失败后发到死信交换机（DLX），人工排查后再补发。
测试延迟精度和堆积场景得关掉 Koa 的默认超时
Koa2 的 server.setTimeout(30000) 会影响长连接，而 RabbitMQ 消费者常驻运行，若中间有慢查询或短信网关响应慢，Node.js 进程可能被 kill。务必在启动时显式设置：
const server = app.listen(3000); server.setTimeout(0); // 关闭超时
测试延迟精度时，别只测 1s 延迟——x-delayed-message 在毫秒级有误差（实测 ±200ms），真正业务用至少 5s 起步；压测堆积量时，注意 RabbitMQ 内存水位，超过阈值会阻塞生产者，得配合 max-length 和 overflow=reject-publish 队列参数防雪崩。
插件版本和 Erlang 版本强相关，RabbitMQ 3.8+ 推荐用插件 3.8.x，混用高版本插件和低版本 Erlang 会导致延迟消息完全不触发。
