Go 报错 cannot assign to entry in nil map 怎么解决？nil map 的正确初始化与 4 种修复姿势

报错现场

这是 Go 初学者最高频的报错之一，编译完全通过，一运行就 panic：

panic: assignment to entry in nil map

goroutine 1 [running]:
main.main()
        /tmp/main.go:9 +0x1c

复现代码只有几行：

package main

import "fmt"

func main() {
	var m map[string]int // 只声明，没有初始化
	m["a"] = 1           // 💥 panic: assignment to entry in nil map
	fmt.Println(m)
}

一、报错原因：map 是引用类型，零值是 nil

Go 的变量声明 var m map[string]int 只是把 m 初始化为零值 nil——此时 m 没有指向任何底层哈希表（hmap）。向 map 写入元素需要往哈希桶里放数据，没有底层数据结构自然无处安放，运行时直接 panic。

这也解释了面试里的经典追问：为什么 nil map 能读不能写？

• 读 v := m["a"]：运行时判断 m 为 nil，直接返回零值，不产生副作用，安全；
• 写 m["a"] = 1：需要修改底层结构（可能还要扩容、迁移），nil 指针无处修改，panic；
• delete(m, "a")：对 nil map 删除同样不 panic（Go 语言规范明确允许，空操作）；
• len(m) / for range m：安全，结果为 0 / 不进入循环。

本质上和 《深入理解 Go Map 底层实现》 讲的结构有关：map 的增删都可能触发哈希桶扩容，只有「读」这条路径对 nil 做了特殊兜底。

二、4 种修复姿势

姿势 1：make 初始化（最常用）

m := make(map[string]int)
m["a"] = 1

make 会在堆上创建 hmap 和第一批哈希桶，m 指向真正的数据结构，读写都正常。

姿势 2：字面量直接赋值（声明即填充）

m := map[string]int{"a": 1, "b": 2}

字面量语法在编译器底层同样会生成初始化逻辑，等价于 make + 逐个赋值。

姿势 3：先判 nil 再懒初始化

适合「这个 map 不一定用得到」的场景，避免白分配内存：

var m map[string]int

func add(k string, v int) {
	if m == nil {
		m = make(map[string]int)
	}
	m[k] = v
}

注意 if m == nil 对 map 是合法的：nil 是 map 合法的零值，可以直接和 nil 比较（slice 的 nil 比较则不行，编译报错）。

姿势 4：让构造函数返回初始化好的 map

多人协作时，把「构造 + 初始化」收敛到一个地方，杜绝调用方拿到裸 map：

type UserStore struct {
	byID map[int64]string
}

func NewUserStore() *UserStore {
	return &UserStore{
		byID: make(map[int64]string), // 初始化责任在构造函数
	}
}

func (s *UserStore) Add(id int64, name string) {
	s.byID[id] = name // 永远不会 panic
}

这本质上和 sync.Once / 构造函数模式是同一类防御性设计（参考 《sync.Once 底层机制》）。

三、nil map vs nil slice 行为对照表

很多 confusion 来自用 slice 的经验去套 map。记住下面这张表，这类坑就不会再踩：

一句话总结：slice 的 append 自带「懒初始化」，map 的赋值没有——这就是为什么 nil slice 随便用，nil map 一写就崩。

四、进阶：并发写 map 是另一个 panic

修好了 nil map，多 goroutine 并发写入还会撞上第二个经典 panic：

fatal error: concurrent map writes

这个错误不可 recover（不是普通 panic），直接整个进程退出。原因与解法见 《Go map 是并发安全的吗？》：map 内部没有任何锁，并发场景请改用 sync.RWMutex 包一层，或直接使用 sync.Map。判断口诀：同一时刻只有一个 goroutine 碰 map → 用普通 map；读写并发且读多写少 → RWMutex；键值集合动态变化、读写都频繁 → sync.Map。

五、排查清单（下次 30 秒定位）

遇到 assignment to entry in nil map 按这个顺序查：

1. 找到 panic 堆栈里你自己的那一行（main.go:行号），定位是哪个 map；
2. 搜索这个 map 的所有声明点，看是否存在 var xxx map[K]V 但没有 make 的分支；
3. 常见场景：结构体字段忘了在构造函数初始化、函数返回了 nil map、错误分支提前 return 导致初始化代码没执行；
4. 顺手检查并发写入： panic 文本是 assignment to entry in nil map 还是 concurrent map writes，两者解法完全不同。

结语

cannot assign to entry in nil map 的根因只有一个：声明了 map 却没有初始化就写入。修复优先级：能确定要用就 make / 字面量；不确定就用「判 nil 懒初始化」；多人协作就把初始化收进构造函数。再记住 nil map「可读不可写」和 nil slice 的对照表，这道题就彻底拿下了。

相关阅读：深入理解 Go Map 底层实现：哈希冲突、扩容迁移与并发安全 · Go map 是并发安全的吗？ · sync.Once 底层机制解析 · Go语言面试题总目录