php-amqplib/php-amqplib是PHP集成RabbitMQ的唯一推荐纯PHP客户端，兼容PHP 7.4–8.3与RabbitMQ 3.9–4.x，需执行composer require php-amqplib/php-amqplib:^3.6安装，严格按序传入AMQPStreamConnection五参数（含vhost），并确保autoload.php置于脚本顶部且RabbitMQ服务已独立部署启动。
php-amqplib/php-amqplib 是当前 PHP 项目集成 RabbitMQ 的事实标准，不是“可选方案”，而是唯一推荐的纯 PHP 客户端。它不依赖 C 扩展、无编译门槛、兼容 PHP 7.4–8.3 和 RabbitMQ 3.9–4.x，装完就能跑。
composer require php-amqplib/php-amqplib 为什么必须加版本约束
直接执行 composer require php-amqplib/php-amqplib 会装最新版（目前是 v3.6+），但生产环境应显式锁定最小兼容版本：
-
composer require php-amqplib/php-amqplib:^3.6—— 推荐。修复了 v2 中连接复用 bug，支持 RabbitMQ 4.x 的 headers 传递（如延迟队列插件需要） - 避免写
"php-amqplib/php-amqplib": "v3.0.0"—— v3.0.0 缺失 AMQP 1.0 协议头支持，某些管理界面或插件调用会静默丢 header - 别信
composer require rabbitmq或rabbitmq/rabbitmq—— 这些包不存在，Composer 会报错或装空包
require_once vendor/autoload.php 必须在最前，且不能被包裹
很多 Class 'PhpAmqpLib\Connection\AMQPStreamConnection' not found 错误，根本不是类名写错，而是 autoloader 没加载：
- 必须放在脚本顶部，且不能在
try/catch、if块或函数体内 - 错误写法：
if (true) { require_once 'vendor/autoload.php'; }→ 类找不到 - CLI 环境下注意工作目录：如果执行
php src/producer.php，而autoload.php在上层，需先cd到项目根目录，或改用php -d "include_path=.:./vendor/autoload.php" src/producer.php - 框架项目（Laravel/ThinkPHP）无需手动 require，但修改
composer.json的psr-4映射后，务必执行composer dump-autoload
AMQPStreamConnection 构造参数顺序不能错
new AMQPStreamConnection($host, $port, $user, $pass, $vhost) 这 5 个参数必须严格按序传入，漏掉 $vhost（哪怕用默认 '/'）会导致后续操作失败：
立即学习“PHP免费学习笔记（深入）”；
- 现象：连接成功，但
$channel->queue_declare()报ACCESS_REFUSED - Login was refused或NOT_FOUND - no queue 'xxx' in vhost '/' - 正确写法：
new AMQPStreamConnection('localhost', 5672, 'guest', 'guest', '/')—— 第 5 位'/'不可省略 - 第 6 参数为
$insist（bool），默认false；若启用了 TLS，需设为true并传入$stream_context_options - 生产环境别每次发消息都新建连接：
AMQPStreamConnection是长连接，但 FPM 下无法跨请求复用，应封装为单例或连接池（简单场景可用静态属性缓存）
消息持久化和队列声明的关键参数组合
要让消息和队列在 RabbitMQ 重启后不丢失，光设 delivery_mode => 2 不够，必须配合队列声明参数：
- 队列声明必须设
durable => true（第 3 参数）：$channel->queue_declare('task_queue', false, true, false, false) - 消息发送时设
'delivery_mode' => AMQPMessage::DELIVERY_MODE_PERSISTENT（等价于2） - 漏掉任一者，重启 RabbitMQ 后队列消失或消息丢失
- 不要用
auto_delete => true（第 4 参数）—— 它会让队列在最后一个消费者断开后自动删除，和持久化目标冲突
真正容易被忽略的是：装完 php-amqplib 只是有了“发请求的工具”，RabbitMQ 服务本身仍需独立部署、启动、配用户权限。本地测试记得先跑 docker run -d -p 5672:5672 -p 15672:15672 rabbitmq:management，再验证连接。
