rdkafka扩展需正确链接librdkafka库并配置多sapi环境，生产者必须调用flush和poll，消费者须设group.id与auto.offset.reset，且需确认kafka服务可达。
PHP 要真正用上 Kafka，rdkafka 扩展不是“装了就能跑”，它依赖底层 librdkafka，且配置稍有偏差就会报错或静默失败——比如 php -m | grep rdkafka 显示已加载，但 new RdKafkaProducer() 直接 fatal error，这种问题八成出在链接或版本不匹配上。
确认 librdkafka 已正确安装并可被 PHP 扩展找到
PHP 的 rdkafka 扩展是 C 扩展，必须链接到编译好的 librdkafka 动态库。很多失败不是因为没装，而是没被找到。
- Linux 下运行
ldconfig -p | grep rdkafka，应看到类似librdkafka.so.1 (libc6,x86-64) => /usr/lib/x86_64-linux-gnu/librdkafka.so.1的输出；若无，需手动执行sudo ldconfig或把库路径加进/etc/ld.so.conf.d/rdkafka.conf - Ubuntu/Debian 推荐用
sudo apt-get install librdkafka-dev（含头文件），而非源码编译——后者容易漏掉pkg-config信息，导致pecl install rdkafka编译时找不到librdkafka - Mac 用户若用
brew install librdkafka，注意pecl install rdkafka有时仍会找不到 pkg-config 描述，可临时设环境变量：PKG_CONFIG_PATH=/opt/homebrew/lib/pkgconfig pecl install rdkafka
安装 rdkafka 扩展后必须验证类是否可用，而非仅看模块列表
php -m 只说明扩展加载成功，不代表类能实例化。常见错误如 Class 'RdKafkaProducer' not found，往往是因为扩展虽加载，但 PHP 没读到其类定义（典型于多 SAPI 环境）。
- 分别检查 CLI 和 Web（如 Apache/FPM）的
php.ini：CLI 通常用/etc/php/*/cli/php.ini，FPM 用/etc/php/*/fpm/php.ini，两者都要加extension=rdkafka.so - 写一个最小验证脚本：
<?php var_dump(class_exists('RdKafka\Producer')); var_dump(class_exists('RdKafka\KafkaConsumer')); ?>，在 CLI 和 Web 环境下都跑一遍 - Windows 用户注意 DLL 名称：新版扩展名是
rdkafka.dll，不是php_rdkafka.dll；ini 中写extension=rdkafka即可（PHP 7.4+ 自动补 .dll）
生产者代码里最容易丢消息的两个动作：flush 和 poll
很多人照抄示例写了 $topic->produce() 就以为发出去了，结果 Kafka 里根本收不到——消息还卡在内存缓冲区里。
-
$producer->flush(5000)是强制清空所有待发送消息的阻塞调用，超时返回非RD_KAFKA_RESP_ERR_NO_ERROR时必须处理，否则消息永久丢失 -
$producer->poll(0)不是可选的：它负责触发后台线程回调（比如 delivery report），不调用会导致dr_cb不执行、错误无法捕获、甚至缓冲区满后produce()报RD_KAFKA_RESP_ERR__QUEUE_FULL - 推荐结构：
$conf = new RdKafkaConf(); $conf->set('dr_cb', function ($kafka, $message) { if ($message->err) { error_log("Delivery failed: " . rd_kafka_err2str($message->err)); } }); $producer = new RdKafkaProducer($conf); // ... produce ... $producer->flush(5000); // 必须放在最后
消费者启动前必须确保主题存在且 offset 可读
直接跑消费者代码却收不到消息？大概率是 KafkaConsumer 默认从 OFFSET_BEGINNING 或 OFFSET_END 开始消费，但主题压根没数据，或 ACL 权限没开。
- 先用命令行确认主题存在：
kafka-topics.sh --bootstrap-server localhost:9092 --list - 消费者代码中必须显式设置
group.id和auto.offset.reset：$conf = new RdKafkaConf(); $conf->set('group.id', 'test-group'); $conf->set('auto.offset.reset', 'smallest'); // 或 'earliest' $consumer = new RdKafkaKafkaConsumer($conf); $consumer->subscribe(['test']); while (true) { $message = $consumer->consume(1000); // 1000ms timeout if ($message->err) { if ($message->err == RD_KAFKA_RESP_ERR__PARTITION_EOF) continue; throw new RuntimeException($message->errstr()); } echo $message->payload . " "; } - 注意：如果 Kafka 启用了 SASL/SSL，
rdkafka需额外配置sasl.username、security.protocol等，这些参数名和 Java 客户端不一致，必须查librdkafka文档，不能凭经验填
最常被跳过的环节是：没确认 Kafka broker 是否真的监听在你写的地址上（比如 Docker 网络里 host.docker.internal 不通，或 server.properties 里 advertised.listeners 配错），导致连接被拒绝却只报超时。建议先用 kafka-console-consumer.sh 连通再写 PHP 代码。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
