用 docker 跑单节点 kafka 应直接使用 kraft 模式（kafka_process_roles=broker,controller），禁用 zookeeper；sarama 生产者需显式设 requiredacks=waitforall、return.successes=true、version 精确匹配，并避免 nsq 替代 kafka 本地调试。
用 Docker 跑单节点 Kafka，别碰 ZooKeeper 旧模式
本地开发根本不需要 ZooKeeper——KRaft 模式从 Kafka 3.3+ 就已稳定，2026 年新项目直接跳过 zk 那套。Docker 启动时若还沿用 zookeeper-server-start.sh，等于给自己埋个启动失败、端口冲突、日志刷屏的雷。
- 用官方镜像
apache/kafka:3.6（匹配你线上版本），启用 KRaft：加KAFKA_PROCESS_ROLES=broker,controller和KAFKA_NODE_ID=1 - 必须显式指定
KAFKA_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093和KAFKA_LISTENER_SECURITY_PROTOCOL_MAP=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT - 挂载数据卷时避开 macOS 的
/tmp（Docker Desktop 会卡住），改用/var/lib/kafka-data - 验证是否跑通：执行
docker exec -it kafka bash -c "kafka-topics.sh --bootstrap-server localhost:9092 --list"，有输出就说明 broker 已就绪
sarama.NewSyncProducer 默认配置会静默丢消息
新手最常踩的坑是以为 NewSyncProducer 天然“可靠”——其实它默认 RequiredAcks = sarama.NoResponse，发完就返回，Broker 即使宕机也报 success。
- 必须手动设
config.Producer.RequiredAcks = sarama.WaitForAll，否则acks=all形同虚设 - 必须开
config.Producer.Return.Successes = true，否则SendMessage返回的partition和offset全是零值，没法做幂等校验或重试定位 -
config.Version必须精确匹配 Kafka 版本，比如用3.6却配sarama.V2_8_0，会报UNKNOWN_TOPIC_OR_PARTITION且不提示版本错 - 本地网络抖动频繁，
config.Net.DialTimeout和config.Net.ReadTimeout建议设为10 * time.Second，低于 5 秒容易断连不重试
别用 kafka-console-consumer 直接测 Go 生产者
控制台消费者默认 auto.offset.reset=latest，而 Go 生产者发完消息可能还没刷盘，或者 consumer 启动慢了半秒，结果看到“没消息”，第一反应是代码错了——其实是时机问题。
- 测生产者是否真发出去，优先用
kafka-console-consumer.sh --from-beginning --bootstrap-server localhost:9092 --topic your-topic - 如果 topic 是新创建的，先用
kafka-topics.sh --create显式建好，别依赖 auto.create.topics.enable=true（本地调试时这个开关常被关） - Go 端发完消息后，别立刻 exit，加
time.Sleep(200 * time.Millisecond)再结束，给 Kafka 批处理和刷盘留时间 - 检查消息体是否合法：用
StringEncoder时传空字符串或 nil 会 panic；用ByteEncoder则要确保字节切片非 nil
NSQ 不适合替代 Kafka 做本地开发对齐
有人图省事用 NSQ 模拟 Kafka，但两者语义差异太大：NSQ 不保证顺序、无 partition、无 offset 提交机制。用它调通了，换到 Kafka 上大概率出消费乱序、重复、漏消息的问题。
立即学习“go语言免费学习笔记（深入）”；
- NSQ 的
nsq.Producer默认不自动重连，网络抖动一次就卡死，而 Kafka 的 sarama 会自动重试（前提是配置了Retry.Max） - NSQ 没有
acks=all级别的持久化确认，Publish返回成功 ≠ 消息落盘 - 如果你最终上生产用的是 Kafka，本地就该用 Kafka——Docker 启一个单节点成本远低于写两套适配逻辑
- 实在想轻量，可用
kafka-go库的kgo.Client，比 sarama 更现代，API 更简洁，且对 KRaft 支持更原生
本地环境最容易被忽略的不是“怎么跑起来”，而是“怎么确认它真按你预期工作”。比如 RequiredAcks 设错、Version 不匹配、consumer 启动时机偏差——这些都不会报明显错误，只会让消息在某个环节无声消失。调试时多看 broker 日志里的 INFO LogDirFailureWatcher 和 WARN RequestSendThread 行，比盯着 Go 程序 panic 有用得多。
