Composer 安装 php-amqplib/php-amqplib 是纯 PHP 的 RabbitMQ 客户端，非 C 扩展 amqp；后者需系统级编译安装，检查用 php -m | grep amqp 或 phpinfo()；Linux 用 apt install php-amqp，macOS 用 brew + pecl，Windows 推荐改用 php-amqplib。
Composer 安装 amqp 扩展前必须确认 PHP 已编译支持 amqp
直接运行 composer require php-amqplib/php-amqplib 装的是纯 PHP 实现的 RabbitMQ 客户端，不是 PHP 的 amqp 扩展（即基于 librabbitmq 的 C 扩展）。后者需系统级编译安装，composer 无法替代。如果你看到 Class 'AMQPConnection' not found 或 Extension 'amqp' not loaded，说明你缺的是扩展本身，不是 Composer 包。
- 检查是否已启用：
php -m | grep amqp或phpinfo()中搜索amqp - Linux（Ubuntu/Debian）常见安装路径：
sudo apt install php-amqp（注意 PHP 版本后缀，如php8.1-amqp） - macOS（Homebrew + php@8.2）：先
brew install rabbitmq-c，再pecl install amqp，最后在php.ini加extension=amqp - Windows 用户基本绕不开 DLL —— 必须匹配 PHP 线程安全（TS/NTS）、架构（x64/x86）和版本，推荐改用
php-amqplib/php-amqplib
用 composer require php-amqplib/php-amqplib 集成 RabbitMQ
这是最常用、跨平台、无需扩展依赖的方案，适用于 95% 的 Web 场景。它通过 AMQP 协议原生与 RabbitMQ 通信，性能足够，调试友好。
- 安装命令：
composer require php-amqplib/php-amqplib - 连接示例（带基础错误防护）：
$connection = new \PhpAmqpLib\Connection\AMQPStreamConnection( 'localhost', 5672, 'guest', 'guest', '/', false, 'AMQPLAIN', null, 'en_US', 30, 30 ); $channel = $connection->channel(); - 注意第 6 参数
false表示不使用 SSL；若启用了 TLS，需传true并配置stream_context_options - 生产环境务必封装连接逻辑，避免每次请求都新建
AMQPStreamConnection—— 它是长连接，但不能跨 PHP 请求复用（FPM 模式下）
AMQP 扩展（amqp.so）和 php-amqplib 性能与兼容性差异
两者不是“替代关系”，而是“不同层级”：C 扩展更底层、更快（尤其高吞吐消息收发），但维护成本高；php-amqplib 更灵活、易调试、支持更多 AMQP 0.9.1 特性（如延迟插件、死信路由）。
- 吞吐量参考（本地 RabbitMQ）：C 扩展发送 10k 条消息约快 15–20%，但差距在 PHP 层逻辑复杂时被掩盖
- php-amqplib 支持
AMQPExchange::setArgument('x-delayed-type', 'direct')，C 扩展对延迟队列等插件支持弱或需手动构造 header - PHP 8.2+ 下，C 扩展存在部分函数签名变更（如
AMQPChannel::basic_consume()回调参数顺序），而 php-amqplib 已适配 - Docker 环境中，
php:8.2-cli镜像默认不含amqp扩展，但可直接composer installphp-amqplib
连接失败常见报错与快速定位方法
别急着重装，先看错误来源是网络、认证，还是协议层问题。
-
Connection refused (111)→ RabbitMQ 服务未运行或端口被防火墙拦截，执行telnet localhost 5672 -
ACCESS_REFUSED - Login was refused→ 用户名密码错，或该用户没被授权访问指定 vhost（检查rabbitmqctl list_permissions -p /） -
AMQP protocol error: REPLY_CODE=530→ vhost 不存在，比如代码连的是/myapp，但 RabbitMQ 里只建了/ - php-amqplib 报
Broken pipe or closed connection→ 网络不稳定或心跳超时，可在构造AMQPStreamConnection时调大第 9、10 参数（heartbeat 和 timeout）
真正麻烦的是扩展加载成功但行为异常——比如消息发出去却没进队列，这时得开 RabbitMQ Management UI 看 Exchange 绑定、Queue 状态、Unacked 数量，而不是继续折腾 PHP 配置。
