php 8.3 连 rabbitmq 应使用 php-amqplib 而非 amqp 扩展，因后者不支持 php 8.3，编译易报 undefined symbol 错误；php-amqplib 是纯 php 实现，兼容 7.4–8.3，执行 composer require php-amqplib/php-amqplib:^3.6 即可。
PHP 8.3 项目要连 RabbitMQ，别装 amqp 扩展——它在 PHP 8.3 上编译极不稳定，官方 PECL 包至今无正式支持，硬上大概率遇到 undefined symbol: zend_string_init 或 ZEND_ACC_FINAL undeclared 这类报错。直接用 php-amqplib/php-amqplib 是唯一靠谱路径。
为什么不用 amqp.so 而用 php-amqplib
因为 amqp 扩展是 C 写的，强依赖 rabbitmq-c 库版本和 PHP 内核 ABI。PHP 8.3 的内存模型和 ZTS/NTS 行为有调整，amqp 1.11.0（当前最新）只明确支持到 PHP 8.1；1.12.x 尚未发布，GitHub issue 中大量 PHP 8.3 编译失败报告。而 php-amqplib 是纯 PHP 实现，无扩展依赖，composer require php-amqplib/php-amqplib:^3.6 装完即用，已通过 PHP 7.4–8.3 全版本 CI 验证。
安装 php-amqplib 的实操要点
运行以下命令（注意版本约束）：
composer require php-amqplib/php-amqplib:^3.6
关键细节：
-
^3.6是目前最稳的分支：修复了 v2 的连接复用 bug，兼容 RabbitMQ 3.9–4.x，且完整支持headers和delivery_mode=2持久化 - 别写死
"php-amqplib/php-amqplib": "3.0.0"—— v3.0.0 缺少 AMQP 1.0 协议头解析，某些管理插件或延迟队列场景会丢x-delay等 header -
require_once __DIR__.'/vendor/autoload.php'必须放在脚本最顶部，不能包在if、函数或try里，否则类找不到 - CLI 下运行时，确保当前工作目录是项目根目录；若从子目录执行，用
php -d "include_path=.:./vendor/autoload.php" src/worker.php
AMQPStreamConnection 构造参数顺序不能错
这个构造函数严格按顺序接收 5 个参数：$host, $port, $user, $pass, $vhost。漏掉 $vhost（哪怕用默认值 '/'）会导致连接成功但后续声明队列失败，报错如：
ACCESS_REFUSED - Login was refused on vhost '/'
正确写法示例：
$connection = new AMQPStreamConnection('rabbitmq', 5672, 'guest', 'guest', '/');
常见错误：
- 误写成
new AMQPStreamConnection('localhost', ...)—— Docker 环境下应填服务名rabbitmq，不是localhost - 把
$vhost当作可选参数跳过，实际它是必填项 - 端口填错：5672 是 AMQP 端口，15672 是管理界面端口，连错直接 timeout
Docker 环境中网络与权限配置
docker-compose.yml 中必须显式定义共用 network，并确认 RabbitMQ 容器启用了 management 插件：
services:
rabbitmq:
image: rabbitmq:4.0-management
ports:
- "5672:5672"
- "15672:15672"
environment:
- RABBITMQ_DEFAULT_USER=guest
- RABBITMQ_DEFAULT_PASS=guest
networks:
- mynet
<p>php-app:
build: .
networks:</p>
- mynet
PHP 容器内连接时，
host必须写rabbitmq（即 service 名），不能写localhost或容器 IP；vhost 若非默认'/'，需提前在管理界面或用rabbitmqctl创建并赋权。
最容易被忽略的是：RabbitMQ 默认 vhost '/' 对 guest 用户仅允许本地连接（loopback），Docker 容器间属于远程连接，必须显式修改权限或换用户。临时解决可运行：rabbitmqctl set_permissions -p / guest ".*" ".*" ".*" —— 生产环境务必改用专用用户。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
