推荐使用 composer require php-amqplib/php-amqplib:^3.6 安装，因其纯 PHP 实现、无扩展依赖、兼容 PHP 7.4–8.3 及 RabbitMQ 3.9–4.x，且修复了连接复用问题。
composer require php-amqplib/php-amqplib 是唯一推荐方式
PHP 官方不提供 RabbitMQ 原生扩展（amqp.so）的跨平台稳定支持，Windows 下编译困难、Linux 下版本耦合严、PHP 8.1+ 兼容性差；而 php-amqplib/php-amqplib 纯 PHP 实现，无扩展依赖，Composer 安装即用，适配所有主流 PHP 版本（7.4–8.3），是当前最可靠的选择。
实操建议：
- 直接在项目根目录运行：
composer require php-amqplib/php-amqplib:^3.6（推荐^3.6，兼容 RabbitMQ 3.9–4.x，且修复了 v2 中的连接复用 bug） - 不要写
"php-amqplib/php-amqplib": "v3.0.0"这类固定版本——v3.0.0 缺少对 AMQP 1.0 协议头的支持，会导致某些管理插件或延迟队列场景下 headers 丢失 - 若项目已禁用 packagist 镜像，需确认网络可访问
https://packagist.org；国内用户建议提前配置阿里云镜像：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
require_once vendor/autoload.php 必须放在最前，且不能被条件跳过
很多初学者把 require_once __DIR__.'/vendor/autoload.php' 写在 try/catch 里、或封装进某个方法中，结果报错 Class 'PhpAmqpLib\Connection\AMQPStreamConnection' not found——这不是类名写错，是 autoloader 根本没加载。
关键点：
立即学习“PHP免费学习笔记（深入）”；
-
autoload.php必须在任何use或实例化前执行，且不能被 if/else、函数作用域包裹 - 如果使用 ThinkPHP、Laravel 等框架，无需手动 require——框架已接管 autoloader，但要确认
composer dump-autoload已执行（尤其修改了psr-4映射后） - CLI 环境下运行时，注意工作目录是否为项目根目录；错误示例：
php ./src/producer.php而autoload.php在上层 —— 应改用php -d "include_path=.:./vendor/autoload.php" src/producer.php或统一 cd 到项目根再运行
AMQPStreamConnection 构造参数顺序和默认值容易出错
new AMQPStreamConnection($host, $port, $user, $pass, $vhost) 这 5 个参数必须严格按顺序传入，漏掉 $vhost（哪怕用默认 '/'）会导致连接成功但后续声明队列失败，报错类似：ACCESS_REFUSED - Login was refused 或 NOT_FOUND - no queue 'hello' in vhost '/'。
常见陷阱：
- 误写成
new AMQPStreamConnection('localhost', 5672, 'guest', 'guest')（缺$vhost）→ 实际连的是vhost = ''，而 RabbitMQ 默认只允许访问'/' - 本地开发用 Docker 时，
$host不能填'localhost'（那是容器外的宿主机 loopback），应填'rabbitmq'（Docker 网络别名）或'host.docker.internal'（Mac/Win） -
$port默认是5672，不是 HTTP 管理端口15672；填错会卡在连接超时，而非认证失败
basic_publish 和 basic_consume 的 exchange 参数为空字符串有特殊含义
调用 $channel->basic_publish($msg, '', $queueName) 时第二个参数传空字符串 ''，表示使用 RabbitMQ 的「默认交换机（default exchange）」，它会自动把消息路由到与 $queueName 同名的队列——这是最简模式，但也是最容易误解的一点。
为什么要注意：
- 如果你先声明了队列
hello，又用basic_publish($msg, 'my_exchange', 'hello')，但没事先exchange_declare('my_exchange')，就会报错：NOT_FOUND - no exchange 'my_exchange' in vhost '/' - 消费者用
basic_consume($queueName, ...)时，第一个参数是队列名，不是交换机名；它不关心消息从哪个交换机来，只从指定队列取数据 - 生产环境务必显式声明 exchange + queue + binding，避免依赖默认行为；测试脚本可以偷懒，但上线前要补全
RabbitMQ 的 PHP 客户端看似简单，真正卡住人的从来不是语法，而是连接上下文（vhost/host/port）、AMQP 协议语义（default exchange 的隐式路由）、以及 Composer 自动加载的时机——这三处一旦错位，错误信息往往不指向真实原因。
