phpEnv下需手动编译rdkafka：先静态编译librdkafka至用户目录，再用对应版本phpize/php-config编译php-rdkafka，最后在该版本php.ini中启用extension=rdkafka.so。
phpEnv 环境下不能直接用 pecl install rdkafka，因为 phpEnv 自带的 PHP 是编译安装、未启用 PECL 通道，且默认不带 phpize 和 php-config 符号链接。必须手动编译 php-rdkafka，并确保路径指向 phpEnv 对应版本的二进制工具。
确认 phpEnv 的 PHP 版本和路径
phpEnv 安装的 PHP 通常位于 ~/.phpenv/versions/ 下，比如 ~/.phpenv/versions/8.1.22。先确认当前激活版本：
- 运行
phpenv version查看当前版本名（如8.1.22） - 执行
which php，输出类似~/.phpenv/shims/php，再用phpenv which php获取真实路径，如~/.phpenv/versions/8.1.22/bin/php - 对应地，
php-config在~/.phpenv/versions/8.1.22/bin/php-config，phpize在同目录 - 注意：不要用系统级的
/usr/bin/phpize，否则会链接到错误的 PHP 头文件，导致编译失败或运行时 segfault
手动编译安装 librdkafka（必须静态链接）
phpEnv 下的 PHP 扩展依赖动态库，但 librdkafka 默认安装到 /usr/local/lib，而 phpEnv 的 PHP 运行时可能不加载该路径。更稳妥的做法是静态编译并指定 --enable-static --disable-shared，避免运行时找不到 librdkafka.so：
- 下载并进入源码：
git clone https://github.com/edenhill/librdkafka.git && cd librdkafka - 配置静态构建：
./configure --enable-static --disable-shared --prefix=$HOME/.phpenv/librdkafka - 编译安装：
make && make install - 这样头文件和静态库都落在用户目录，后续
php-rdkafka编译时可精准引用
编译 php-rdkafka 并启用 extension
关键点在于 ./configure 时显式指定 librdkafka 的头文件和库路径，否则会 fallback 到系统路径，和你刚装的不一致：
立即学习“PHP免费学习笔记（深入）”；
- 克隆扩展：
git clone https://github.com/arnaud-lb/php-rdkafka.git && cd php-rdkafka - 用 phpEnv 版本的
phpize初始化：~/.phpenv/versions/8.1.22/bin/phpize - 配置时绑定自定义 librdkafka：
./configure --with-php-config=~/.phpenv/versions/8.1.22/bin/php-config --with-rdkafka=$HOME/.phpenv/librdkafka - 编译安装：
make && make install，成功后会提示Installing shared extensions: .../rdkafka.so - 在 phpEnv 当前版本的
php.ini中添加：extension=rdkafka.so（路径通常是~/.phpenv/versions/8.1.22/etc/php.ini） - 验证：
php -m | grep rdkafka，有输出即成功；若报错undefined symbol: rd_kafka_version，说明 librdkafka 动态链接失败，退回上一步检查--with-rdkafka路径是否正确
连接 Kafka 时常见的 broker.list 配置陷阱
php-rdkafka 的 metadata.broker.list 不接受域名别名（如 kafka），也不自动解析 /etc/hosts 里的映射——它走的是 libc 的 getaddrinfo，但容器或某些网络环境下 DNS 解析会失败。最稳写法是 IP + 端口：
- 本地开发用 Docker Compose？别写
kafka:9092，改用宿主机 IP（如172.17.0.1:9092）或host.docker.internal:9092（Docker Desktop 支持） - Kafka 服务端
server.properties中的advertised.listeners必须和客户端写的地址一致，否则消费者 fetch 失败，报错Failed to resolve "xxx:9092" - 测试连通性别只靠
telnet localhost 9092，Kafka 协议不是纯 TCP 握手，要用kafka-console-consumer.sh或php -r "new RdKafka\Consumer(new RdKafka\Conf());"实际触发元数据请求
最易被忽略的是：phpEnv 每次切换 PHP 版本，rdkafka.so 都得重新编译一次，不能共用；而且 php.ini 是按版本隔离的，改错文件位置会导致 extension 不生效，连 php -m 都看不到。动手前务必 phpenv which php 和 php --ini 双确认路径。
