PHP连接RabbitMQ必须安装amqp扩展而非仅Composer包，需匹配rabbitmq-c与PHP版本，正确配置phpize/php-config路径，Docker中用服务名而非localhost，并注意vhost、端口类型及重启php-fpm。
PHP 要用 RabbitMQ，必须装 amqp 扩展，不是装个 Composer 包就能连上；服务端和扩展版本不匹配，AMQPConnection 会直接报错或静默失败。
Linux 下编译安装 amqp 扩展前，必须先装对版本的 rabbitmq-c
PHP 的 amqp 扩展是 C 写的，它不直接连 RabbitMQ，而是调用底层 C 库 rabbitmq-c（也叫 librabbitmq）。这个库的版本和 PHP 版本强相关：
- PHP 5.6–7.2：建议用
rabbitmq-cv0.8.0 或 v0.9.0，v0.11.0+ 可能编译失败或运行时段错误 - PHP 7.4–8.1：用 v0.13.0 或 v0.14.0 更稳妥；v0.11.0 在某些 OpenSSL 1.0.x 环境下会报
/usr/bin/ld: cannot find -lrabbitmq - 编译完
rabbitmq-c后，务必检查输出目录是否有lib/librabbitmq.so（或lib64/librabbitmq.so），并创建软链：ln -s /usr/local/rabbitmq-c-0.13.0/lib64 /usr/local/rabbitmq-c-0.13.0/lib -
./configure时必须指定--with-librabbitmq-dir=/usr/local/rabbitmq-c-0.13.0，路径末尾不能带斜杠，否则make会找不到头文件
PHP 8.0+ 必须用 amqp 1.11.0+，且 phpize 和 php-config 路径要严格匹配
低版本 amqp（如 1.9.4）在 PHP 8 上无法编译通过，常见报错包括 undefined symbol: zend_string_init 或 error: ‘ZEND_ACC_FINAL’ undeclared：
- 下载地址固定为：
https://pecl.php.net/get/amqp-1.11.0.tgz（截至 2026 年 4 月仍是最新稳定版） - 执行
/usr/bin/phpize前，先确认它属于目标 PHP 版本：/usr/bin/phpize --version；若用宝塔，路径类似/www/server/php/80/bin/phpize -
./configure必须带全三个参数：--with-php-config=/www/server/php/80/bin/php-config --with-amqp --with-librabbitmq-dir=/usr/local/rabbitmq-c-0.13.0 - 如果
make报fatal error: amqp.h: No such file or directory，说明rabbitmq-c的include没被找到，检查/usr/local/rabbitmq-c-0.13.0/include/amqp.h是否存在
Docker 环境中连接 RabbitMQ，别写 localhost 或 127.0.0.1
PHP 容器和 RabbitMQ 容器在 Docker 网络里是不同主机，localhost 指向容器自己，不是宿主机或另一容器：
立即学习“PHP免费学习笔记（深入）”；
-
docker-compose.yml中需定义同一 network，并用服务名作为 host：host: rabbitmq（前提是 service 名叫rabbitmq） - 连接代码里不能硬编码
'host' => 'localhost'，应从环境变量读取：getenv('RABBITMQ_HOST') ?: 'rabbitmq' - 默认用户
guest在新版 RabbitMQ（3.12+）中禁止远程登录，启动时必须显式设置：-e RABBITMQ_DEFAULT_USER=admin -e RABBITMQ_DEFAULT_PASS=admin - 管理界面端口
15672和 AMQP 端口5672需分别映射，且防火墙要放行；用telnet rabbitmq 5672在 PHP 容器内测试连通性
AMQPConnection 连接失败时，优先查扩展是否加载、vhost 是否存在、凭据是否过期
连接报错但没具体信息，往往不是网络问题，而是服务端配置或扩展状态异常：
- 先运行
php -m | grep amqp，无输出说明扩展根本没加载；若有输出但代码报Class 'AMQPConnection' not found，说明php.ini里extension=amqp.so路径写错了，或没重启php-fpm - RabbitMQ 默认 vhost 是
/，但 URL 编码后是%2F，PHP 扩展里传参必须写成'vhost' => '/'，不能写'vhost' => '%2F'，否则认证失败 - 使用
AMQPConnection构造时，'port'必须是整数，字符串'5672'会导致连接超时而不报错 - 如果
$conn->connect()返回false，调$conn->getLastError()才能看到真实错误，比如Connection refused（端口不通）或ACCESS_REFUSED（用户无权限）
最常被跳过的一步：改完 php.ini 后，只 reload nginx，忘了 systemctl restart php-fpm 或 kill -USR2 主进程——扩展加载发生在 PHP 启动时，不是请求时。
