Java Map.copyOf 为什么不接受 null 键和值

Map.copyOf 不接受 null 键和值，是它创建不可修改 Map 时的明确 API 契约，并不是 HashMap 不能存 null。源 Map 本身为 null，或包含任意 null 键、null 值，都会导致 NullPointerException。解决时先确定空值在业务中的含义：拒绝、过滤、替换为明确默认值，或者保留 null 并选择允许它的复制与包装方式。

Java 官方 API：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/Map.html

先找出输入 Map 中的空键与空值

这类错误常出现在把可变缓存、配置或查询结果转成只读映射的交接处。输入原来使用 HashMap，可以保存一个 null 键和多个 null 值；copyOf 对输出施加了更严格的内容约束。它不会自动跳过空项，也不会猜测 null 应换成什么。

import java.util.HashMap;
import java.util.Map;

public class NullCopyExample {
    public static void main(String[] args) {
        Map input = new HashMap();
        input.put("region", "east");
        input.put("memo", null);
        try {
            // 故意保留空值，说明异常发生在转换边界。
            Map.copyOf(input);
        } catch (NullPointerException expected) {
            System.out.println("输入包含空键或空值，不能直接复制");
        }
    }
}

预期进入 catch 分支；这里未提供本机运行记录。定位时同时检查 map 对象、entry 的键和 entry 的值，不要只根据异常栈里出现 copyOf 就修改 JDK 参数。

把无空值约束放到数据入口

如果约定配置不允许空值，入口明确拒绝比转换时才抛出笼统异常更容易定位。以下方法保留字段名相关的诊断，但不把可能敏感的完整配置值写进异常：

import java.util.HashMap;
import java.util.Map;
import java.util.Objects;

public class ConfigSnapshot {
    public static Map freeze(Map input) {
        Objects.requireNonNull(input, "配置映射不能为空");
        Map checked = new HashMap();
        for (Map.Entry entry : input.entrySet()) {
            // 字段名仅用于受控诊断；不要在日志中打印配置值。
            String key = Objects.requireNonNull(entry.getKey(), "配置键不能为空");
            String value = Objects.requireNonNull(
                entry.getValue(), "配置值不能为空，字段：" + key);
            checked.put(key, value);
        }
        return Map.copyOf(checked);
    }
}

若 null 表示“没有提供这个字段”，可以在业务转换层过滤；若表示“有字段但尚未填写”，删除它就改变了语义。默认值也应由领域规则确定，不能统一用空字符串掩盖缺失。上述方法需要 Java 10 及以上的 Map.copyOf；它是普通方法示例，不负责解决输入 Map 被其他线程同时修改的问题。

确实需要 null 时复制后再包装

对确实保留 null 的接口，可以使用 HashMap 保存映射，再通过 Collections.unmodifiableMap 暴露不可修改视图。关键是先复制，避免调用方继续修改原 Map 时影响结果。下面同时展示两种包装的差异：

import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

public class NullableSnapshot {
    public static void main(String[] args) {
        Map source = new HashMap();
        source.put("memo", null);

        // 直接包装仍关联原表，原表变化对 view 可见。
        Map view = Collections.unmodifiableMap(source);
        // 先复制到独立 backing；不再把 backing 交给其他写入方。
        Map backing = new HashMap(source);
        Map safe = Collections.unmodifiableMap(backing);

        source.put("region", "west");
        System.out.println(view.containsKey("region"));
        System.out.println(safe.containsKey("region"));
        System.out.println(safe.containsKey("memo"));
    }
}

按结构关系，三个表达式预期分别为 true、false、true。safe 保留 memo 这个键，其值仍为 null。若其他代码持有 backing 并修改它，safe 仍会反映那些变化；因此独立副本及其写入所有权都要管理，包装器本身不是深度冻结工具。

查询语义和可变值仍需单独处理

允许 null 的 Map 中，get 返回 null 可能表示“键不存在”，也可能表示“键存在且值为 null”；需要区分时使用 containsKey。对于拒绝 null 的 Map，不要假定传入 null 查询参数一定只会返回 false 或 null，API 对不合格查询参数允许实现抛出异常。调用前仍应遵守非空契约。

不可修改限制的是映射结构。若 value 是 ArrayList 等可变对象，外部仍可能修改该对象的内容。需要稳定快照时，应复制或转换这些值；键对象也应避免在存入后修改影响 equals、hashCode 的状态。要求输出顺序时应另选有明确顺序约定的方案，不把 copyOf 当作保留源 Map 遍历顺序的承诺。

迁移时保留异常信息与清理职责

迁移时建议分别覆盖源对象为 null、空键、空值、正常映射和可变 value。先确认输入契约再处理异常，不要捕获所有异常后返回空 Map，这会把“没有数据”和“输入错误”混在一起。Map 中若存有文件或连接等资源，删除映射不等于自动关闭它们，资源释放应遵循原有所有权规则。

copyOf 会删除源 Map 的 null 项吗？不会，它拒绝这类输入，而不是替你清洗源表。

用 unmodifiableMap 包装 HashMap 后还能保留 null 吗？可以，包装视图沿用底层映射内容；先复制再包装可隔离原表后续结构修改。

copyOf 每次都创建新对象吗？不应依赖对象身份来判断复制效果，契约关注映射内容与修改约束；不要把 == 当作业务正确性检查。

相关官方 API：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/Collections.html；https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/HashMap.html。