rdkafka是PHP集成Kafka的首选方案，因纯PHP客户端易丢消息；需先装librdkafka系统库再pecl install rdkafka，配置advertised.listeners和group.id等关键参数避免连接失败。
RdKafka 扩展是当前 PHP 集成 Apache Kafka 最稳定、性能最好的选择，不是“可用就行”，而是“必须用它”——纯 PHP 客户端（如 kafka-php）在高吞吐、长连接、错误恢复等场景下容易丢消息或卡死，生产环境不建议。
为什么不用 pecl install kafka 就报错？
常见现象：pecl install kafka 失败，或安装后 php -m | grep kafka 没输出，或运行时报 Class 'RdKafkaProducer' not found。
根本原因不是命令错了，而是依赖链没理清：
-
rdkafka扩展底层依赖librdkafkaC 库（不是 Java 的 Kafka 客户端），必须先装系统级库，再编译扩展 - Ubuntu/Debian：运行
sudo apt-get install librdkafka1-dev librdkafka1；CentOS/RHEL：用yum install librdkafka-devel librdkafka1 - PHP 版本要 ≥ 7.2（
rdkafka4.x 要求 ≥ 7.4；5.x 要求 ≥ 8.0），用php -v确认 - 装完
librdkafka后，再执行pecl install rdkafka（注意不是kafka），然后在php.ini中加extension=rdkafka.so - 最后重启 PHP-FPM 或 Apache，用
php --ri rdkafka验证是否加载成功
生产者发不出消息？检查这 4 个硬参数
90% 的“发不出”问题出在配置项上，不是代码逻辑错，而是 broker 连接或 topic 元数据没拉下来。
-
$producer->addBrokers('localhost:9092')中的地址必须能被 PHP 进程直接访问（Docker 环境别写localhost，改用宿主机 IP 或host.docker.internal） - 必须调用
$producer->newTopic($topic)获取 topic 对象，不能直接对 producer 调produce() -
RD_KAFKA_PARTITION_UA是“未指定分区”，但首次使用前 Kafka 要 fetch metadata，超时默认 10 秒；若网络慢，需提前设$conf->set('metadata.broker.list', '...')和$conf->set('socket.timeout.ms', '30000') - 消息体不能是
null或未序列化的对象，produce()第三个参数必须是string；传数组请先json_encode()
消费者收不到消息？先看 offset 和 group.id
消费者“启动了但没输出”，大概率是 offset 位置不对，或 group 已消费过、没重置。
立即学习“PHP免费学习笔记（深入）”；
-
group.id必须是字符串，且所有同组消费者共用一个；测试时建议每次换新名（如test-group-20260411），避免受历史 offset 影响 - 用
$conf->set('auto.offset.reset', 'earliest')强制从头读（仅开发/调试），生产环境应设为latest并确保 commit 正常 - 消费者必须调
$consumer->subscribe([$topic])，不是addBrokers()后就自动监听 - 消费循环必须手动
poll()，典型结构是：while (true) { $message = $topicConsumer->consume(1000); if ($message->err) { ... } else { echo $message->payload; } } - 如果用的是旧版
kafka-php库，它默认走 ZooKeeper 协调，而 Kafka 3.3+ 已弃用 ZK 模式，会导致消费者静默失败
跨网络或 Docker 场景连不上？别只改 server.properties
常见错误是只配了 server.properties 的 host.name，但漏了 advertised.listeners。
- Kafka 启动后会把
advertised.listeners返回给客户端作为“后续通信地址”；如果这里填的是内网 IP 或localhost，PHP 客户端拿到后会尝试连错地址 - 单机开发：设
advertised.listeners=PLAINTEXT://localhost:9092 - Docker + host 网络：设
advertised.listeners=PLAINTEXT://host.docker.internal:9092，并在容器启动时加--add-host=host.docker.internal:host-gateway - 真实集群跨机器：
advertised.listeners必须填客户端能路由到的公网/内网 IP，且对应端口在防火墙放行 - 验证方式：用
kafka-console-consumer.sh --bootstrap-server xxx:9092 --topic test --from-beginning能连上，PHP 才可能连上
advertised.listeners 配错导致连接被重定向到不可达地址，或是 group.id 复用导致以为没消息其实是 offset 已提交。这些点不打提前量，查日志要花两小时。 
