Go maps.Clone 传入 nil map 时返回值是什么

如果把一个 nil map 传给 maps.Clone，返回值仍然是 nil，不会自动变成一个可写的空 map。它的 len 是 0，按键读取会得到 value 类型的零值；但直接写入会触发 panic: assignment to entry in nil map。因此，判断“有没有数据”和判断“能不能写入”要分开。

最短结论：maps.Clone(nilMap) 保留 nil 语义；需要写入时，先判断返回值是否为 nil，再决定保留 nil 还是用 make 初始化。

为什么 maps.Clone(nil) 仍然是 nil

maps.Clone 的泛型签名会返回与输入相同的 map 类型。官方文档把它定义为 copy，并特别说明这是 shallow clone：键和值通过普通赋值复制。对 nil 输入而言，复制后没有可枚举的键值，nil 状态也会保留下来。

可以先用一个最小示例观察判断逻辑：

package main

import (
    "fmt"
    "maps"
)

func main() {
    var source map[string]int // 只声明，不分配 map 存储
    cloned := maps.Clone(source)

    fmt.Println(cloned == nil) // true：nil 语义被保留
    fmt.Println(len(cloned))   // 0：读取长度安全
    fmt.Println(cloned["go"])  // 0：缺失键返回 int 的零值
}

这里的三个结果并不矛盾。map 的读取操作可以作用于 nil map，缺失键只返回零值；但写入需要真实的 map 存储区域，nil map 没有这个区域。

nil map 与空 map 不能只看 len

排查配置、请求参数或缓存快照时，最容易误判的是把 len(m) == 0 当成“可以写入”。nil map 和 make(map[string]int) 创建的空 map 都是零长度，但它们的写入能力不同。

所以在函数边界上，nil 可能有业务含义，例如“字段未提供”；空 map 则可能表示“字段已提供但当前没有键”。如果只关心有没有条目，可以看 len；如果下一步要赋值，还必须检查 nil 状态。

需要写入时，先决定是否初始化

一个实用写法是把 Clone 和初始化分成两个意图：保留输入的 nil 语义，或者把结果转换成可写容器。不要在调用 maps.Clone 后无条件赋值。

func cloneForWrite(source map[string]int) map[string]int {
    cloned := maps.Clone(source)
    if cloned == nil {
        cloned = make(map[string]int) // 业务要求结果可写时再分配
    }
    cloned["source"] = 1
    return cloned
}

如果 nil 代表“没有配置”，就应该保留 nil，并让调用方继续识别这个状态；如果返回值要进入后续合并流程，则可以在明确的边界上初始化。这个选择属于数据契约，不应靠 len == 0 猜测。

自定义 map 类型也遵循同一规则：

type Labels map[string]string

func cloneLabels(in Labels) Labels {
    out := maps.Clone(in) // 返回值仍是 Labels，而不是普通 map
    if out == nil {
        out = make(Labels) // 只有这里完成可写初始化
    }
    out["stage"] = "ready"
    return out
}

浅复制要把嵌套 value 单独看待

外层 map 的键值槽会被复制，但 value 如果本身是 slice、map、指针或包含引用的结构体，复制的只是这个引用值。下面的例子中，修改新 map 的字符串键不会影响原 map；修改其中 slice 的元素，则可能影响两边看到的内容。

func cloneWithSlice(source map[string][]int) map[string][]int {
    cloned := maps.Clone(source)
    if cloned == nil {
        cloned = make(map[string][]int) // 防止外层 map 写入 nil panic
    }
    cloned["extra"] = []int{9} // 新增外层键，不会写入 source
    cloned["items"][0] = 99   // slice value 仍可能共享底层数组
    return cloned
}

这就是“map 已经 Clone 了，为什么嵌套数据还会一起变”的来源。需要完全隔离时，要针对 value 类型再复制一层，例如为每个 slice 分配新切片并使用 copy；不能把 maps.Clone 当成递归深拷贝。

相关问题

maps.Clone(nil) 会返回一个空 map 吗？

不会。返回值仍是 nil map。它和空 map 一样可以读取、长度为 0，但不能直接写入。

如何判断 Clone 后的 map 能不能写？

不要只检查 len，应使用 cloned == nil。为真时先按业务决定是否调用 make。

maps.Clone 会深复制 slice value 吗？

不会。它是浅复制，外层 map 独立，但 slice、map、指针等嵌套引用仍可能共享底层对象。

小结：maps.Clone 传入 nil map 时，返回值保留 nil；读取安全不代表写入安全。写入前处理初始化，嵌套引用再按 value 类型单独复制，才能让 map 的语义和数据隔离边界保持一致。