必须先确认RabbitMQ版本，插件需与主版本号严格匹配；下载对应版本的rabbitmq_delayed_message_exchange.ez文件；正确复制到plugins目录并设置权限；启用插件后声明x-delayed-message交换机并用x-delay header发送消息。
必须先确认 RabbitMQ 版本，插件版本不匹配会导致 rabbitmq-plugins enable 失败、服务无法启动，甚至容器直接崩溃。
查清 RabbitMQ 版本再下载插件
延迟插件 rabbitmq_delayed_message_exchange 与 RabbitMQ 主版本号（如 3.11.x、3.12.x）严格绑定，小版本（如 3.12.0 vs 3.12.1）通常兼容，但大版本跨升（如 3.11 → 3.12）必须换插件。
- 执行
rabbitmqctl version获取准确版本号（注意不是rabbitmq-server --version，后者可能不显示补丁号） - 去 GitHub Releases 页面：rabbitmq-delayed-message-exchange/releases
- 找和你
rabbitmqctl version输出完全一致的.ez文件，例如输出是3.12.0，就下rabbitmq_delayed_message_exchange-3.12.0.ez - 别信“最新版通用”——3.12.x 插件在 3.11.x 上会报
missing dependency: rabbitmq_server-3.12.0
Linux 原生安装：复制 + 启用 + 权限三步到位
插件文件必须放在 RabbitMQ 自身识别的 plugins 目录里，且属主属组要设对，否则启用时静默失败。
- 用
rabbitmq-plugins directories查真实插件路径（常见但非绝对路径：/usr/lib/rabbitmq/lib/rabbitmq_server-3.12.0/plugins/） sudo cp rabbitmq_delayed_message_exchange-3.12.0.ez /usr/lib/rabbitmq/lib/rabbitmq_server-3.12.0/plugins/sudo chown rabbitmq:rabbitmq /usr/lib/rabbitmq/lib/rabbitmq_server-3.12.0/plugins/rabbitmq_delayed_message_exchange-3.12.0.ezsudo chmod 644 /usr/lib/rabbitmq/lib/rabbitmq_server-3.12.0/plugins/*.ez- 执行
sudo rabbitmq-plugins enable rabbitmq_delayed_message_exchange（注意命令里不带版本号和 .ez） - 重启服务：
sudo systemctl restart rabbitmq-server
Docker 环境：严禁直接挂载 plugins 目录
把宿主机目录 -v /host/plugins:/plugins 挂载进容器，会覆盖掉 RabbitMQ 自带的核心插件（如 rabbitmq_management），导致启动时报 Failed to load module 'rabbit'。
- 推荐方式一（构建镜像）：Dockerfile 中
COPY插件到/opt/rabbitmq/plugins/，再RUN rabbitmq-plugins enable ... - 推荐方式二（运行时注入）：
docker cp rabbitmq_delayed_message_exchange-3.12.0.ez container_name:/opt/rabbitmq/plugins/，再docker exec -it container_name rabbitmq-plugins enable rabbitmq_delayed_message_exchange - 验证是否生效：
docker exec container_name rabbitmq-plugins list | grep delayed，看到[E*] rabbitmq_delayed_message_exchange才算成功 - Web 管理界面中，Exchanges → Add a new exchange → Type 下拉框出现
x-delayed-message是最终确认点
声明交换机和发消息：参数名和 header 必须精确
插件启用后不会自动创建交换机，必须显式声明；延迟时间必须通过 x-delay header 传，不是 expiration，也不是队列 TTL。
- 声明交换机（命令行）：
rabbitmqadmin declare exchange name=delayed_exchange type=x-delayed-message arguments='{"x-delayed-type":"direct"}' - 发送消息（命令行）：
rabbitmqadmin publish exchange=delayed_exchange routing_key=test_queue payload="timeout" properties='{"headers":{"x-delay":60000}}'（60 秒后投递） - Spring Boot 中要用
CustomExchange，type 设为"x-delayed-message"，并设置argument("x-delayed-type", "direct") - Java 生产者发消息时，必须用
MessageProperties设置 header：messageProperties.getHeaders().put("x-delay", 60000)，不能设setExpiration("60000")—— 那是 TTL 方案用的
最易忽略的一点：插件启用后，x-delayed-message 交换机默认不支持 topic 路由，如果你需要通配符匹配，必须在声明时指定 x-delayed-type 为 topic，否则 routing_key 不生效。这个参数一旦设错，消息会静默丢失，连死信都进不去。
