structuredClone能安全深拷贝Map、Set、Date等复合结构并保持键类型与顺序;自动递归处理嵌套,但不支持函数、undefined、DOM节点等,遇不可克隆值抛DataCloneError。

structuredClone 能直接、安全地深拷贝包含 Map、Set、Date、RegExp、ArrayBuffer、TypedArray、BigInt、Object、Array 等在内的复合结构,无需额外处理 —— 它原生支持这些类型。
Map 和 Set 会被正确克隆
与 JSON.parse(JSON.stringify()) 不同,structuredClone 保留 Map 的键值对顺序、原始键类型(包括对象、函数、Symbol 作为键)和 Set 的唯一元素。例如:
✅ 正确克隆(键为对象、Symbol、字符串混合):
const original = new Map();
const keyObj = { id: 1 };
const keySym = Symbol('a');
original.set(keyObj, 'objValue');
original.set(keySym, 'symValue');
original.set('str', 'stringValue');
const cloned = structuredClone(original);
// cloned 是独立的新 Map,keyObj 和 keySym 在 cloned 中仍可访问
console.log(cloned.get(keyObj)); // 'objValue'(注意:keyObj 是原对象,但 cloned 是新 Map 实例)
⚠️ 注意:克隆后,Map/Set 中的引用类型(如对象、数组)本身也被深拷贝,但原始键对象不会被“替换”——也就是说,cloned.get(keyObj) 依然有效,因为 structuredClone 对 Map 键做了等价映射(内部使用结构化克隆算法维护键的可比性)。
立即学习“Java免费学习笔记(深入)”;
嵌套结构自动递归处理
只要整个结构可被结构化克隆(即不含函数、undefined、window、DOM 节点、WeakMap/WeakSet 等不可克隆值),无论嵌套多深,structuredClone 都能完整还原:
-
Map的值是Set→Set被克隆 -
Set的元素是Map→Map被克隆 -
Array包含Map和Set→ 各自独立克隆 -
Object的属性值含Map/Set→ 属性值被深拷贝
示例:
const data = {
users: new Set([{ name: 'Alice' }, { name: 'Bob' }]),
config: new Map([['theme', 'dark'], ['lang', 'zh']]),
logs: [new Date(), new Set(['error'])]
};
const copy = structuredClone(data);
// copy.users 是新 Set,内部对象也被深拷贝
// copy.config 是新 Map,内容一致但独立
// copy.logs[0] 是新 Date 实例,copy.logs[1] 是新 Set
不支持的值会直接报错,不静默失败
如果结构中含以下任一类型,structuredClone 会抛出 DataCloneError:
- 函数(
function、箭头函数) -
undefined、NaN(NaN实际上是支持的,但某些旧版浏览器可能有差异;现代标准中NaN可克隆) -
WeakMap、WeakSet - DOM 元素、
window、document -
Error对象(如new Error())
因此,使用前建议确保数据纯净,或用 try/catch 捕获并降级处理。
浏览器兼容性需留意
目前(2024 年中)主流浏览器均支持:
- Chrome 98+、Edge 98+
- Firefox 94+
- Safari 15.4+
Node.js 17.0+ 原生支持(需启用 --experimental-structured-cloning 的版本已过时;Node.js 17.0+ 默认开启)。
若需兼容旧环境,可用 ungap/structured-clone 这类轻量 polyfill(基于 MessageChannel 实现,支持 Map/Set)。


















