应根据场景选择：开发调试用 nmred/kafka-php，生产高吞吐必须用 php-rdkafka 扩展；前者通过 composer require 安装，后者需系统级安装扩展并声明 ext-rdkafka 依赖。
composer require 该选哪个包？
rdkafka/rdkafka 和 nmred/kafka-php 是两个完全不同的东西：前者是 PHP 的原生 C 扩展封装（需编译安装），后者是纯 PHP 实现的 Kafka 客户端库。你用 composer require 装不了 rdkafka/rdkafka——它根本不在 Packagist 上，官方要求你先装系统级扩展 php-rdkafka，再通过 ext-rdkafka 这个虚拟包名让 Composer 认可依赖。
所以实际选择只有两种路径：
- 想快速验证、开发调试、不介意性能损耗 → 用
nmred/kafka-php（或ka/kafka-php） - 要上生产、扛高吞吐、消息不能丢 → 必须走
php-rdkafka扩展路线，composer require ext-rdkafka只是声明依赖，不是安装本体
注意：quipo/kafka-php 已归档多年，ka/kafka-php 是其 fork 但维护松散，2026 年主流项目基本都切到 nmred/kafka-php 或直接上 rdkafka 扩展。
装了 composer 包却报 Class not found？
这是最常卡住人的一步。如果你用了 nmred/kafka-php 却看到 Class 'Kafka\Producer' not found，大概率是没跑 composer install 或自动加载失效：
立即学习“PHP免费学习笔记（深入）”；
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 确保在项目根目录执行了
composer install（不是require后就完事） - 检查
vendor/autoload.php是否被正确引入（常见漏掉require_once） - 运行
composer dump-autoload -o强制重建优化类映射
而如果你选的是 ext-rdkafka 路线，报错通常是 Class 'RdKafka\Producer' not found 或 Extension 'rdkafka' not loaded——这说明 PHP 根本没加载扩展，跟 Composer 无关。此时要检查：
-
php.ini里是否写了extension=php_rdkafka.dll（Windows）或extension=rdkafka.so（Linux/macOS） -
php -m | grep rdkafka是否输出扩展名 -
phpinfo()页面里有没有rdkafka模块区块
配置 broker 地址时 localhost:9092 为什么连不上？
localhost 在容器或远程部署场景下极易出问题：Docker 内 PHP 容器访问宿主机 Kafka，localhost 指向的是容器自己，不是你的宿主机；Kubernetes 中更得用 Service DNS 名。
- 开发环境推荐统一用
host.docker.internal:9092（Docker Desktop）或宿主机真实 IP（如192.168.1.100:9092） - 生产环境必须用集群内网地址，且确保 Kafka 的
advertised.listeners配置对外暴露的是消费者能反向连接的地址，否则会卡在 metadata 获取阶段 -
nmred/kafka-php默认不支持 SASL/SSL，如果 Kafka 开了安全认证，要么换rdkafka扩展（原生支持），要么手动打补丁或改用其他兼容库
另外，setBrokerVersion('0.9.0.1') 这类调用别乱设——版本填错会导致协议解析失败，Consumer 直接静默退出，日志里可能只有一句 Failed to resolve metadata。
异步发送后消息“消失”了？
nmred/kafka-php 的异步模式（setIsAsyn(true)）本质是把消息塞进内存队列后立即返回，并不保证已发到 Kafka。如果脚本结束前没调 $producer->send(true) 或没等 flush 完成，消息就丢了。
- 同步模式更稳：设
setIsAsyn(false)，每次send()都阻塞等待 broker ack - 异步模式必须配
flush()或监听success/error回调，且确保脚本生命周期足够长（比如 CLI 命令行，不是 Web 请求） -
rdkafka扩展里对应的是$producer->flush(5000)，超时时间太短（如 100ms）也会导致看似成功实则未发出
真正容易被忽略的是：Kafka 主题不存在时，nmred/kafka-php 默认不会自动创建（取决于 Kafka 配置 auto.create.topics.enable），而 rdkafka 扩展在 topic 不存在时会直接抛异常，不处理就会中断整个流程。
