Libp2p在Go中需显式配置Transport、StreamMuxer等核心组件，否则无法通信；multiaddr必须含有效PeerID；Stream读写须处理EOF和context取消以避免泄漏。
Libp2p 在 Go 项目中不是「引入就能用」的库，它是一套可组合的网络协议栈，直接 go get 后若不理解其核心抽象（Host、Network、Stream、PeerStore），大概率卡在连不上、收不到消息、甚至 panic。
初始化 Host 时必须显式配置 Transport 和 StreamMuxer
默认 libp2p.New() 不启用任何传输层，连 tcp 都没有，启动后 host.Addrs() 返回空切片是正常现象——不是代码错了，是根本没配 transport。
- 必须显式传入
libp2p.Transport(libp2p.TCPTransport)（或QUICTransport） - 必须配至少一个流多路复用器：
libp2p.StreamMuxer(libp2p.MSMuxer)或libp2p.YAMUX，否则host.NewStream()会 panic - 若要支持 NAT 穿透，需额外加
libp2p.NATPortMap()和libp2p.EnableRelay()
示例最小可用配置：
host, err := libp2p.New(
libp2p.ListenAddrStrings("/ip4/0.0.0.0/tcp/0"),
libp2p.Transport(libp2p.TCPTransport),
libp2p.StreamMuxer(libp2p.MSMuxer),
libp2p.Security(libp2p.NoSecurity),
)
连接对端前必须先解析 multiaddr 并确保 PeerID 有效
Libp2p 不接受裸 IP:Port，所有地址必须是完整 multiaddr 格式，且包含校验过的 PeerID。常见错误是把 /ip4/127.0.0.1/tcp/9000 直接传给 host.Connect()，结果报错 "failed to parse peer ID"。
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- multiaddr 字符串末尾必须带
/p2p/Qm...，例如/ip4/127.0.0.1/tcp/9000/p2p/12D3KooW... - PeerID 必须由对方的公钥生成，不能手写或截断；可用
peer.IDFromPublicKey()验证 - 若从字符串解析，务必用
ma.ParseMultiaddr()+peer.AddrInfoFromP2pAddr()拆解，别自己字符串拼接
读写 Stream 必须处理 EOF 和 context cancel
Libp2p 的 Stream 是双向、带生命周期的连接抽象，不是裸 TCP Conn。忽略上下文或不检查 io.EOF 会导致 goroutine 泄漏或静默失败。
- 所有
stream.Read()和stream.Write()应包裹在select中监听ctx.Done() -
stream.Close()关闭写端，stream.CloseRead()关闭读端；单向关闭后另一端仍可读/写，直到对方也关闭 - 收到
io.EOF表示对端已关闭写端，此时应主动stream.Close()，否则该 stream 会滞留
典型安全读循环：
for {
select {
case <-ctx.Done():
return ctx.Err()
default:
}
n, err := stream.Read(buf)
if err != nil {
if err == io.EOF {
return nil
}
return err
}
// 处理 buf[:n]
}
PeerStore 和路由不是自动同步的，跨节点发现需手动维护
Libp2p 默认不广播节点信息，host.Peerstore().AddAddr() 只存本地缓存，重启即丢。若两个节点从未直连过，又没手动注入对方地址，host.Connect() 必然超时。
- 测试阶段可用
host.Peerstore().AddAddrs(peerID, []ma.Multiaddr{addr}, peerstore.Permanent)预埋地址 - 生产环境需接入 DHT（
libp2p.DHTServer()）、PubSub 或自建 bootstrap 节点列表 - 注意
peerstore.Permanent和peerstore.TempAddrTTL生效时机不同：前者永久，后者需定期刷新
真正麻烦的从来不是连上，而是连上之后——比如对方节点没开 DHT，你的节点却依赖它查路由；或者用了 QUIC 但对方只支持 TCP，协商直接失败。这些协议兼容性问题不会报明确错误，只会静默 fallback 或阻塞。
