Go nil map 可以读取为什么写入就 panic

Go 里最容易误解的地方之一，是 nil map 看起来“能用”：读取不存在的键得到元素零值，len 返回 0，遍历也不会报错；但执行 m["user"] = 1 却会直接触发 panic: assignment to entry in nil map。原因不是键不存在，而是这个 map 变量还没有指向可写的哈希表。

读 nil map 可以，写 nil map 不可以。需要写入时，用 make(map[K]V) 或 map 字面量完成初始化；如果 nil 还承担“调用方没有提供数据”的语义，就在边界处明确区分它和空 map。

这篇按一次典型故障拆开：先看读写差异，再定位初始化遗漏，最后决定是否保留 nil 语义。

为什么 nil map 的读取不会立刻暴露问题

下面的变量只有类型，没有分配可写的 map：

var scores map[string]int

// nil map 读取缺失键时返回 int 的零值。
value, ok := scores["alice"]
fmt.Println(value, ok, len(scores)) // 0 false 0

// nil map 可以安全 range，循环体不会执行。
for name, score := range scores {
	fmt.Println(name, score) // 这里只是展示读取到的元素
}

// 这里不是“新增键失败”，而是整个 map 尚未初始化。
scores["alice"] = 90 // panic: assignment to entry in nil map

Map 索引在 nil map 上找不到键时返回元素类型的零值，双返回值中的 ok 为 false。因此只读代码往往一直正常，直到某个分支第一次写入，故障才出现。

用 make 把变量变成可写的空 map

创建 map 时直接初始化是最清楚的修复：

scores := make(map[string]int)

// make 返回可写的空 map；容量参数只是提示，不是长度上限。
scores["alice"] = 90
scores["bob"] = 82

// 读取存在的键时，ok 才表示确实找到条目。
score, ok := scores["alice"]
if !ok {
	return fmt.Errorf("score for alice is missing") // 把缺失数据交给调用方处理
}
fmt.Println(score)

也可以使用 map[string]int{"alice": 90} 字面量。不要用 new(map[string]int) 代替：它得到的是指向 nil map 的指针，解引用后仍然不能直接写入，除非再对 map 本身调用 make。

函数返回值和结构体字段更容易藏住 nil

很多线上故障不是声明处写错，而是 map 藏在零值结构体或函数返回值里：

type Profile struct {
	Labels map[string]string
}

func newProfile() Profile {
	// 结构体本身可以是零值，但需要写 Labels 时必须初始化字段。
	return Profile{Labels: make(map[string]string)}
}

func addLabel(profile *Profile, key, value string) {
	if profile.Labels == nil {
		profile.Labels = make(map[string]string) // 延迟初始化，保持调用方写法简单
	}
	profile.Labels[key] = value
}

排查时沿着“谁创建、谁返回、谁第一次写”反向查：配置解码是否没有该字段，工厂函数是否返回了零值，指针是否指向未初始化的结构体。若 map 是可选输入，调用方可以先判断 m == nil；若函数的职责是返回可写集合，则应在函数内部保证非 nil。

nil 和空 map 怎么选

两者都可以读取且长度为 0，但语义不同。nil 常用来表达“未提供、未知或尚未加载”；make(map[K]V) 表达“已经准备好，只是目前没有元素”。对外返回数据时，如果 JSON、缓存或补丁接口需要区分“字段缺失”和“字段存在但为空”，应保留这个差异；如果下游只需要不断写入，就在边界统一初始化。

最终可以记成三条：读取前不必为了 nil map 强行 make；任何元素赋值前必须确保 map 非 nil；发现 panic 时优先追溯 map 的创建路径，而不是检查键名是否拼错。

相关问题

nil map 能不能 delete？可以，删除不存在的键不会产生效果；但这不改变它不能写入的事实。

nil map 能不能 range？可以，遍历次数为 0。需要输出“未加载”和“加载为空”时，仍要保留 nil 判断。

为什么 map 字段要在构造函数里 make？因为结构体零值会让字段保持 nil，在构造阶段初始化能把写入前置为明确契约。

参考：Go 语言规范 Map types、Index expressions。