Go map 并发写 panic 怎么办：从共享 map 到可控写入路径

线上 Go 服务偶发崩溃，日志里只有一行很醒目的提示：fatal error: concurrent map writes。很多同学第一反应是“加个锁就行”，但真正麻烦的是：到底是哪一段共享 map 被多个 goroutine 同时写？这个问题如果只在低流量下看，很容易被误判成偶发小问题；一旦请求量、定时任务和回调同时压上来，它就会变成稳定的崩溃点。

这篇文章按一个常见问答来拆：Go map 并发写为什么会 panic，如何定位，修复时应该选 sync.Mutex、sync.RWMutex、分片 map、sync.Map，还是单写协程。重点不是背一个答案，而是把写入路径收敛到能解释、能压测、能回归的结构里。

问题现场：为什么流量一上来就 panic

典型日志长这样：

fatal error: concurrent map writes

goroutine 82 [running]:
runtime.throw(...)
runtime.mapassign_faststr(...)

它的意思不是“这个键写错了”，而是 Go 运行时发现同一个普通 map 正在被多个协程并发写入。普通 map 不是并发安全容器，读写和写写同时发生时，内部桶扩容、哈希插入、溢出桶维护都可能处在中间状态。运行时检测到写写冲突时会直接抛出 fatal 级别错误，进程通常无法在业务代码里恢复。

所以第一条结论很直接：只要普通 map 会被多个 goroutine 访问，并且其中至少一个路径会写入，就必须把并发边界显式设计出来。

规模背景：小流量没事，高并发开始放大风险

很多项目最早写共享缓存时都很自然：

var userCache = map[string]User{}

func LoadUser(id string) User {
    if u, ok := userCache[id]; ok {
        return u
    }
    u := queryUser(id)
    userCache[id] = u
    return u
}

本地单人测试时，请求基本是串行的，很难撞上问题。上线后，HTTP 请求、消息消费、后台刷新任务都可能同时调用 LoadUser。当多个请求同时 miss 同一个缓存，再同时写入 userCache，原来隐藏的写写冲突就被放大了。

排查时不要只问“哪里用了 map”，而要问三个更具体的问题：

• 这个 map 是包级变量、结构体字段，还是闭包里被多个协程共享的变量？
• 它有哪些写入入口，包括请求路径、定时刷新、回调处理和测试辅助代码？
• 读路径是否也可能和写路径同时发生，形成数据竞争？

原架构瓶颈：共享 map 被多个 goroutine 直接写

下面这个例子很容易复现问题。它用多个协程同时给同一个普通 map 写计数：

func main() {
    counts := map[string]int{}
    var wg sync.WaitGroup

    for i := 0; i 

这段代码的问题不在 counts[key]++ 看起来短，而在它不是一个原子动作。它包含读取旧值、计算新值、写回 map，写回时还可能触发内部结构调整。多个协程同时做这件事，就会让普通 map 进入不安全状态。

定位时可以先做两类验证：

go test -race ./...

go test -run TestCache -count=50 ./internal/cache

-race 能发现数据竞争，重复运行能放大偶发失败。注意，-race 报告数据竞争并不等同于一定会立刻 panic；它更像是提醒“这里已经有未受控的并发访问”。如果业务日志中已经有 concurrent map writes，就不要再把它归类成偶发现象。

新架构：把写入收敛到可控路径

最小修复通常是加锁。把 map 和锁封装到同一个结构体里，不要把裸 map 暴露给外部调用方：

type CounterStore struct {
    mu     sync.Mutex
    counts map[string]int
}

func NewCounterStore() *CounterStore {
    return &CounterStore{counts: make(map[string]int)}
}

func (s *CounterStore) Add(key string, delta int) {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.counts[key] += delta
}

func (s *CounterStore) Snapshot() map[string]int {
    s.mu.Lock()
    defer s.mu.Unlock()

    copied := make(map[string]int, len(s.counts))
    for k, v := range s.counts {
        copied[k] = v
    }
    return copied
}

这个写法有两个重点。第一，所有读写都必须通过方法进入同一把锁；第二，对外返回快照而不是直接返回内部 map。如果返回内部 map，调用方仍然可以绕过锁写入，问题会换一个地方继续出现。

关键取舍：锁、分片、sync.Map 和单写协程怎么选

修复并发写不是只有一种方案。选型要看读写比例、键空间、热点程度和一致性要求。

方案一：Mutex 或 RWMutex

读写逻辑简单、写入频率不极端时，先用互斥锁。它可读、可维护，也最容易通过代码审查。读多写少时可以考虑 sync.RWMutex，但不要盲目替换：如果写入也很频繁，读锁和写锁的切换成本未必更低。

方案二：分片 map

如果单把锁已经成为热点，可以按 key 哈希拆成多个 shard。每个 shard 有自己的锁和 map，不同 key 大概率落到不同锁上：

type shard struct {
    mu sync.Mutex
    m  map[string]int
}

type ShardedCounter struct {
    shards []shard
}

func (s *ShardedCounter) Add(key string, delta int) {
    part := &s.shards[hashKey(key)%uint32(len(s.shards))]
    part.mu.Lock()
    defer part.mu.Unlock()
    part.m[key] += delta
}

分片的代价是实现复杂度上升，遍历、快照、清理都要跨多个 shard 做一致处理。

方案三：sync.Map

sync.Map 适合读多写少、键相对稳定、并发读路径很多的场景，比如缓存只追加少量新键、配置快照、连接元数据。它不是普通 map 的全面替代品。如果你需要频繁更新计数、批量遍历并删除，普通 map 加锁通常更直观。

方案四：单写协程

如果业务上需要严格顺序、聚合写入或批量落库，可以把写请求通过 channel 交给一个 owner 协程。所有写都在这个协程里完成，其他协程只提交消息。这种方式牺牲了一部分即时性，但能把写入顺序和状态变化讲清楚。

上线结果：看哪些信号确认修好了

修完后不要只看“服务没崩”。至少检查这些信号：

• go test -race ./... 不再报告目标包的数据竞争。
• 压测中 panic 次数为 0，错误率没有被锁等待放大。
• 关键接口的 P95/P99 延迟没有明显劣化。
• 如果用了分片或单写协程，要观察队列长度、锁等待或处理积压。
• 如果用了 sync.Map，要确认 Range、Delete、LoadOrStore 的语义符合业务预期。

如果加锁后接口变慢，说明并发安全问题解决了，但架构瓶颈暴露出来了。接下来才是考虑分片、批量合并、缓存过期策略或异步写入，而不是回到无锁裸写。

后续改进：让并发边界不再靠记忆

这类问题最怕“这次修好了，下次又有人绕过去”。建议把并发边界固化成代码结构和团队规则：

• 共享 map 不以公开字段暴露，只通过方法访问。
• 结构体注释写清楚：由哪把锁保护，哪些方法要求调用方持锁。
• 对缓存、计数器、连接表这类组件保留并发测试。
• 代码审查时看到包级 map 和 goroutine 同时出现，主动追问访问路径。
• 线上 panic 日志要保留 goroutine 堆栈，方便反查写入入口。

快速清单

• 普通 Go map 不能被多个协程并发写。
• 出现 fatal error: concurrent map writes 时，先收敛所有写入入口。
• 简单场景优先封装 map + Mutex，不要返回内部裸 map。
• 高热点场景再考虑分片，读多写少且键稳定时再考虑 sync.Map。
• 需要顺序和聚合时，用单写协程把状态变化排队处理。
• 上线前用竞态检测、重复测试、压测和延迟指标一起确认。

一句话总结：Go map 并发写 panic 不是靠“碰运气少写一点”解决的，而是靠明确所有权。只要把共享状态的读写路径收进一个可控边界，再用测试和压测证明它，问题就会从偶发崩溃变成可维护的工程结构。