Go maps.Clone 如何复制映射并处理 nil 输入

我在整理一段配置复制代码时，最容易误判的不是“能不能复制”，而是复制以后 nil 语义有没有被悄悄改掉。Go 的 maps.Clone 适合解决这个问题：它返回一个新的 map，顶层键和值按普通赋值复制；传入 nil map 时，结果仍然是 nil。

maps.Clone 复制的是哪一层

maps.Clone 的签名是 Clone[M ~map[K]V, K comparable, V any](m M) M，所以键仍须可比较，返回值保留输入 map 的类型。最小用法如下：

package main

import (
	"fmt"
	"maps"
)

func main() {
	source := map[string]int{"retries": 3}
	copyMap := maps.Clone(source)

	// 只修改副本的顶层键，不影响 source。
	copyMap["retries"] = 5
	fmt.Println(source["retries"], copyMap["retries"])
}

这里输出的是 3 5。map 变量本身包含对底层数据结构的引用，直接赋值只会复制引用；而 Clone 会创建新的顶层 map，再把键和值放进去。因此，增加、删除或替换副本的顶层元素，不会改变原 map 的顶层内容。

nil map 和空 map 要分开判断

这两个 map 的 len 都是 0，但语义不同：nil map 还没有初始化，读取安全，写入会 panic；空 map 已初始化，可以写入。官方实现会先保留 nil：

var nilMap map[string]int
emptyMap := make(map[string]int)

// Clone 会保留输入是否为 nil 的状态。
nilCopy := maps.Clone(nilMap)
emptyCopy := maps.Clone(emptyMap)

fmt.Println(nilCopy == nil)   // true：仍是 nil map
fmt.Println(emptyCopy == nil) // false：仍是非 nil 空 map
fmt.Println(len(emptyCopy))   // 0：长度相同，不代表语义相同

如果下游要把 nil 编码成 JSON 的 null，或者用 nil 表示“字段没有提供”，就不要为了方便统一改成 make(map[string]int)。反过来，如果后续必然写入，应该在明确位置初始化，而不是把写入责任交给 Clone。

浅复制不会切断嵌套引用

Clone 对键和值使用普通赋值。值是整数、字符串或不含引用的结构体时，通常符合直觉；值里放了 slice、map 或指针时，内部数据仍可能共享：

type Config struct {
	Tags []string
}

source := map[string]Config{
	"api": {Tags: []string{"internal", "v1"}},
}
copyConfig := maps.Clone(source)

// 这里改的是共享 slice 的元素，原 map 也会看到变化。
copyConfig["api"].Tags[0] = "public"
fmt.Println(source["api"].Tags[0]) // public

如果业务要求完全隔离，就要在复制 map 后，再为每个嵌套字段创建副本，例如用 append([]string(nil), oldTags...) 复制 slice；嵌套 map 则继续调用 maps.Clone，指针指向的结构体需要按字段或构造函数复制。不要把“新 map”直接等同于“深拷贝对象”。

自定义 map 类型和旧环境怎么处理

因为返回类型仍是 M，自定义 map 类型也能直接保留类型：

type Headers map[string]string

headers := Headers{"Accept": "application/json"}
cloned := maps.Clone(headers)

// 返回值仍是 Headers，可继续调用该类型的方法。
fmt.Printf("%T\n", cloned)

项目编译器找不到标准库 maps 时，先确认 Go 版本和模块工具链；这个包随 Go 1.21 引入。若暂时不能升级，可以写一个只负责顶层复制的泛型辅助函数，但仍要主动决定 nil 是否保留：

func cloneMap[K comparable, V any](src map[K]V) map[K]V {
	if src == nil {
		return nil // 保留调用方的 nil 语义
	}
	dst := make(map[K]V, len(src))
	for key, value := range src {
		dst[key] = value // 值中若含引用，仍是浅复制
	}
	return dst
}

常见问题

maps.Clone 会复制嵌套 slice 吗？

不会。它只复制 map 的顶层键和值，嵌套 slice 的底层数组仍可能共享，需要按字段单独复制。

Clone(nil) 和 Clone(make(map[K]V)) 一样吗？

不一样。两者长度都可以是 0，但前者结果为 nil，后者结果为非 nil 空 map；是否可写和序列化语义也不同。

小结

把 map 作为快照、默认配置或请求参数副本时，优先使用 maps.Clone，并在接口边界保留 nil 与空 map 的约定。只要值中出现 slice、map 或指针，就把深拷贝当成另一项明确设计，而不是期待 Clone 自动完成。

参考资料

• Go maps 包文档：https://pkg.go.dev/maps
• Go maps 源码：https://go.dev/src/maps/maps.go
• Go 1.21 发布说明：https://go.dev/doc/go1.21