structuredClone 是浏览器原生深拷贝 API，能替代 JSON.parse(JSON.stringify())，因其支持 Map、Set、Date、RegExp、ArrayBuffer、Error、循环引用等，而 JSON 方案会丢失类型、抛错或静默失败。
structuredClone 是什么，为什么能替代 JSON.parse(JSON.stringify())
structuredClone 是浏览器原生提供的深拷贝 API，支持 Map、Set、Date、RegExp、ArrayBuffer、TypedArray、Error、BigInt 甚至循环引用对象 —— 而 JSON.parse(JSON.stringify()) 会丢掉函数、undefined、Symbol、原型链、Date 对象（变成字符串）、RegExp（变成空对象）、NaN、Infinity，还会在遇到循环引用时直接报错 TypeError: Converting circular structure to JSON。
它不是 polyfill，是真实可用的现代 API：Chrome 98+、Firefox 94+、Safari 16.4+ 已支持。Node.js 17.0+（需启用 --experimental-structured-cloning）也支持，但 Node.js 20.6+ 默认开启。
怎么用 structuredClone 做基础深拷贝
直接传入要拷贝的对象，返回一个全新、独立的副本：
const original = {
name: 'Alice',
scores: [95, 87],
meta: new Date('2023-01-01'),
flags: new Set(['active', 'verified'])
};
<p>const cloned = structuredClone(original);
cloned.scores.push(100);
console.log(original.scores.length); // 2 —— 不受影响
console.log(cloned.meta instanceof Date); // true —— 类型保留
console.log(cloned.flags.has('active')); // true —— Set 完整复制
注意：structuredClone 只接受可结构化克隆（structured-cloneable）的对象。以下类型不支持，调用会抛出 DATA_CLONE_ERR：
立即学习“前端免费学习笔记（深入）”；
-
function、Promise、Generator、AsyncIterator -
Window、Document、Element等 DOM 节点（除非在Worker或MessageChannel场景中） - 带有不可枚举属性或访问器（getter/setter）的对象（只拷贝可枚举自有属性值）
常见踩坑：什么时候不能直接用 structuredClone
需要保留函数或自定义方法：structuredClone 会静默忽略函数属性，不会报错，但结果里没有它。JSON.parse(JSON.stringify()) 同样丢函数，但至少你早有预期；而 structuredClone 看似“更强大”，反而容易漏掉这个限制。
跨 iframe 或 Worker 通信时误用：它底层复用结构化克隆算法（同 postMessage），所以能安全传递复杂对象，但若对象含 DOMException 或某些私有字段（如 AbortController.signal），仍可能失败。
Node.js 环境没开实验特性：Node.js 17–20.5 默认禁用，必须启动时加 --experimental-structured-cloning，否则报 ReferenceError: structuredClone is not defined。
TypeScript 类型提示缺失：旧版 @types/node 或 lib.dom.d.ts 可能未声明，需确保 TypeScript 版本 ≥ 4.8，并检查 lib 配置含 dom 或 es2022。
兼容性 fallback 怎么写才靠谱
需要保留函数或自定义方法：structuredClone 会静默忽略函数属性，不会报错，但结果里没有它。JSON.parse(JSON.stringify()) 同样丢函数，但至少你早有预期；而 structuredClone 看似“更强大”，反而容易漏掉这个限制。
跨 iframe 或 Worker 通信时误用：它底层复用结构化克隆算法（同 postMessage），所以能安全传递复杂对象，但若对象含 DOMException 或某些私有字段（如 AbortController.signal），仍可能失败。
Node.js 环境没开实验特性：Node.js 17–20.5 默认禁用，必须启动时加 --experimental-structured-cloning，否则报 ReferenceError: structuredClone is not defined。
TypeScript 类型提示缺失：旧版 @types/node 或 lib.dom.d.ts 可能未声明，需确保 TypeScript 版本 ≥ 4.8，并检查 lib 配置含 dom 或 es2022。
别用 try/catch 包裹 structuredClone 再退到 JSON.parse(JSON.stringify()) —— 两者能力差距太大，fallback 后行为突变（比如突然丢失 Date 类型），线上难排查。
推荐按场景分级处理：
- 纯数据对象（仅 plain object / array / number / string / null / boolean / Date / RegExp / Set / Map）：优先用
structuredClone - 含函数或特殊实例（如
class MyClass实例）：必须手写clone()方法或用lodash.cloneDeep - 不确定运行环境（老浏览器 or 旧 Node）：检测
typeof structuredClone === 'function'，不支持就明确报错或降级为浅拷贝 + 提示，而不是隐式 fallback
真正麻烦的从来不是“怎么拷贝”，而是“你到底想拷什么”——structuredClone 很诚实，它只拷它认得的东西。
