rdkafka扩展需先用pecl安装并启用，仅Composer引入封装层会导致Class not found；生产者须调用flush()防消息丢失，消费者应禁用自动提交、手动commit确保精确一次语义，且需合理配置acks、offset.reset与poll参数避免重复消费或OOM。
rdkafka 是 PHP 生态中对接 Kafka 的主流客户端，但“用 Composer 安装就完事”这个说法会直接踩进生产环境的坑里——它只是第一步，不是解决方案。
rdkafka 扩展 ≠ rdkafka 包
很多人执行 composer require php-kafka/rdkafka 后发现 KafkaConsumer 报错 Class not found，原因很实在：rdkafka 是一个 PHP 扩展（C 编写的），必须先用 pecl install rdkafka 编译安装，并在 php.ini 中启用 extension=rdkafka.so；Composer 引入的只是它的 PHP 封装层（如 php-kafka/rdkafka 或官方推荐的 arnaud-lb/php-rdkafka），不依赖扩展就运行不了。
- 检查是否加载成功：运行
php -m | grep rdkafka，无输出说明扩展没装好 - 常见编译失败原因：缺少
librdkafka系统库（Ubuntu 上需apt install librdkafka1-dev） - PHP 版本要匹配：PHP 8.1+ 推荐用
arnaud-lb/php-rdkafka:^6，老版本对应 ^4 或 ^5
消费者 offset 提交失败导致重复/丢失
PHP 默认使用 enable.auto.commit=true，看似省事，实则高危：如果消息处理到一半进程崩溃，offset 已提交，那条消息就永远丢失了；反之，若处理完但提交前宕机，重启后会重复消费。
- 必须设为
enable.auto.commit=false - 手动调用
$consumer->commit()或$consumer->commitAsync()，且只在业务逻辑真正完成之后 - 注意
commit()是同步阻塞的，高频场景下会拖慢吞吐；commitAsync()不保证提交成功，需监听回调或配合重试逻辑 - 别忽略
auto.offset.reset=earliest或latest—— 新 consumer group 首次启动时靠它决定从哪开始读
生产者发送超时或返回 success 却没进 Topic
RdKafka\Producer::produce() 返回不报错，不代表消息已落盘。Kafka 生产者是异步缓冲模型，消息先进内存队列，再由后台线程批量发往 broker。如果程序提前 exit，缓冲区里的消息就丢了。
- 务必调用
$producer->flush(5000)（单位毫秒），等所有待发消息完成或超时 - 监听
RD_KAFKA_RESP_ERR__TIMED_OUT和RD_KAFKA_RESP_ERR__MSG_TIMED_OUT错误码，它们意味着 broker 未响应或消息在缓冲区超时 -
message.timeout.ms默认 300000（5 分钟），太长会掩盖网络问题；建议设为 30000–60000 - 别漏掉
acks=all配置（对应 PHP 的acks=-1），否则单节点写入就返回 success，副本同步失败也无感知
流式处理中无法按需暂停/限速
PHP 本身没有原生背压机制，rdkafka 的 poll() 是阻塞调用，但不会自动根据下游处理能力调节拉取节奏。一旦消费速度跟不上，librdkafka 内部缓冲会暴涨，最终 OOM 或触发 max.poll.interval.ms 被踢出 consumer group。
- 用
$consumer->getMetadata()定期检查 lag，当high - committed差值持续 > 1000 时主动 sleep - 控制每次
poll()拉取量：设置fetch.min.bytes=1、fetch.max.wait.ms=100，避免一次拉太多 - 不要在循环里无条件
poll(1000)，应结合业务处理耗时动态调整 timeout，比如处理一条平均 200ms，那就设成 500ms 给 buffer 留余量 - 真实流控还得靠上游限速（如 Nginx 限流）或中间加 Redis 队列削峰，PHP 层只能做兜底
真正卡住的从来不是安装命令，而是扩展与配置的耦合、异步模型的理解偏差、以及对 Kafka “交付语义”的误判。尤其在 PHP 这种无常驻进程特性的语言里，flush、commit、poll 的时机比 Java/Kotlin 严格得多。
