Kafka本地开发需先启动ZooKeeper再启动Kafka，否则syncProducer会连接超时或报UNKNOWN_TOPIC_OR_PARTITION；推荐新手使用ZooKeeper模式，配置时需确保zookeeper.properties的dataDir可写、server.properties中listeners与advertised.listeners匹配本地地址，并正确设置Sarama客户端的RequiredAcks、Return.Successes、Version和Timeout参数。
Kafka 本地开发环境必须先跑通 ZooKeeper（或 KRaft）再起 Kafka，否则 syncProducer 会卡在连接超时或报 UNKNOWN_TOPIC_OR_PARTITION
Windows/macOS/Linux 一键启动 Kafka 单节点（免 ZooKeeper）
从 Kafka 3.3+ 开始，KRaft 模式已稳定，可跳过 ZooKeeper；但多数团队仍用 ZooKeeper 模式——它更成熟、文档全、调试方便。推荐新手走 ZooKeeper 路线，避免版本混淆。
- 下载 Kafka 二进制包（如
kafka_2.13-3.6.0.tgz），解压后进入config/目录 - 确认
zookeeper.properties中dataDir指向一个真实可写的目录（如/tmp/zk-data），否则启动失败且报错模糊 - 先启动 ZooKeeper：
bin/zookeeper-server-start.sh config/zookeeper.properties（macOS/Linux）或bin\windows\zookeeper-server-start.bat config\zookeeper.properties（Windows） - 再启动 Kafka：
bin/kafka-server-start.sh config/server.properties，检查日志末尾是否出现started (kafka.server.KafkaServer) - 创建 topic：
bin/kafka-topics.sh --create --bootstrap-server localhost:9092 --topic test --partitions 1 --replication-factor 1
sarama.NewConfig() 默认配置是生产事故的温床
刚写完 go get github.com/Shopify/sarama 就直接调 NewSyncProducer？大概率发消息不报错但 Broker 根本没收到——因为默认 RequiredAcks = NoResponse，发完就返回成功，连 broker 是否在线都不校验。
- 必须显式设置：
config.Producer.RequiredAcks = sarama.WaitForAll（即acks=all），确保 ISR 全部写入才返回 - 必须开启：
config.Producer.Return.Successes = true，否则SendMessage不返回partition和offset，无法做幂等或追踪 - 必须匹配 Kafka 版本：
config.Version = sarama.V3_6_0（按你实际安装的 Kafka 小版本填），填错会静默失败或报UNSUPPORTED_VERSION -
config.Producer.Timeout建议设为10 * time.Second，太短易因网络抖动误判失败，太长阻塞业务逻辑
Go 客户端连不上？先查这三件事
常见现象：程序卡在 NewSyncProducer 或报 dial tcp 127.0.0.1:9092: connect: connection refused，不是代码问题，是环境没对齐。
立即学习“go语言免费学习笔记（深入）”；
- 确认
server.properties中listeners和advertised.listeners配置正确：本地开发建议都设为PLAINTEXT://localhost:9092；若用0.0.0.0，advertised.listeners必须填可被 Go 进程解析的地址（比如PLAINTEXT://127.0.0.1:9092） - 确认 Kafka 进程真的在运行：
ps aux | grep kafka（Linux/macOS）或任务管理器（Windows），别只看终端窗口没关就以为还在跑 - 确认防火墙没拦：尤其是 macOS 的“防火墙”设置或 Windows Defender 高级安全策略，默认可能拦截
9092端口
最常被忽略的一点：Kafka 的 server.properties 里 broker.id 必须唯一，重装 Kafka 后如果复用旧配置又没清 log.dirs 目录，Broker 会拒绝启动但日志只打一行 Failed to acquire lock on file .lock——得手动删掉 log.dirs 下所有内容才能重启成功。
