使用Laravel-Kafka与Bitnami Kafka时消息头丢失，需集群特殊配置吗？

核心结论 #

Kafka从0.11.0.0版本起原生支持消息头，bitnami/kafka镜像默认配置完全兼容，无需额外集群配置即可传输消息头，问题大概率出在laravel-kafka包的使用或版本上。

排查步骤 #

1. 检查消费者端的读取逻辑 #

很多时候不是消息头没发送，而是消费者没正确读取。确保在消费者处理逻辑中调用getHeaders()方法获取消息头：

Kafka::consume($topic)
    ->withHandler(function (\Junges\Kafka\Messages\Message $message) {
        // 正确获取消息头
        $headers = $message->getHeaders();
        dump($headers); // 验证是否能输出内容
        // 其他业务逻辑
    })
    ->subscribe();

2. 升级laravel-kafka包到最新稳定版 #

部分旧版本的mateusjunges/laravel-kafka存在消息头处理的bug，执行以下命令升级：

composer update mateusjunges/laravel-kafka

3. 确认生产者端配置并补全发送逻辑 #

检查生产者代码是否遗漏了send()方法（未执行该方法消息不会实际发送），同时确保没有手动添加禁用消息头的配置项：

// 正确的发布方式
$message = new \Junges\Kafka\Messages\Message(
    body: ['name' => 'test'],
    headers: ['anotherName' => 'test'],
    key: '1'
);

Kafka::publishOn($topic)
    ->withMessage($message)
    ->send(); // 必须调用send()完成消息发送

4. 用Kafka原生工具验证消息是否携带headers #

绕过laravel-kafka，直接用Kafka自带命令行工具测试，确认问题出在应用层还是Kafka集群：

发送带headers的消息

echo "1:{'name':'test'}:headers=anotherName:test" | kafka-console-producer.sh \
    --broker-list localhost:9092 \
    --topic your-topic \
    --property parse.headers=true \
    --property key.separator=: \
    --property value.separator=:

消费并查看headers

kafka-console-consumer.sh \
    --bootstrap-server localhost:9092 \
    --topic your-topic \
    --from-beginning \
    --property print.headers=true

如果原生工具能正常看到headers，说明问题在laravel-kafka包；如果看不到，可在docker-compose.yml中添加环境变量确保Kafka协议版本达标：

services:
  kafka:
    image: bitnami/kafka:latest
    environment:
      - KAFKA_INTER_BROKER_PROTOCOL_VERSION=2.8.0
      - KAFKA_LOG_MESSAGE_FORMAT_VERSION=2.8.0
      # 保留原有其他配置

内容的提问来源于stack exchange，提问作者behz4d