前端怎样深拷贝含嵌套对象的数据

前端要深拷贝一个含有嵌套对象和数组的数据，优先使用 structuredClone(source)。它会按结构复制可克隆值，复制结果与原对象拥有不同引用；循环引用也能被正确处理。真正容易出问题的地方不是“嵌套层数”，而是数据里混入了函数、DOM 节点、特殊原型对象，或者把 transfer 误当成普通拷贝。

官方参考：https://developer.mozilla.org/en-US/docs/Web/API/Window/structuredClone

先用 structuredClone 复制普通业务数据，再针对不可克隆成员和 ArrayBuffer 转移语义做边界处理；不要默认用 JSON 往返替代，因为它会改变更多数据类型的语义。

• 普通嵌套对象、数组、Map、Set、Date 等结构化可克隆值可以直接处理。
• 函数和 DOM 节点不能被结构化克隆，通常会抛出 DataCloneError。
• 复制不是原型和属性描述符的完整复刻，类实例要先确认自己的数据契约。
• 指定 transfer 时是把可转移资源交给副本，原对象中的资源会失效。

先把“深拷贝成功”拆成三个判断

判断深拷贝是否符合预期，不要只看控制台里对象打印得像不像。至少要分别确认顶层引用不同、嵌套引用不同，以及修改副本不会回写原数据。

// 准备一个包含对象、数组和循环引用的业务数据
const source = {
  profile: { name: "Lin", roles: ["editor"] },
  settings: new Map([["theme", "dark"]]),
};
source.self = source; // 这个循环引用不应让深拷贝陷入无限递归

const copy = structuredClone(source);

copy.profile.roles.push("reviewer"); // 修改副本的嵌套数组
copy.settings.set("density", "compact"); // 修改副本的 Map

console.assert(copy !== source); // 顶层对象必须是新引用
console.assert(copy.profile !== source.profile); // 嵌套对象也必须脱离原引用
console.assert(source.profile.roles.length === 1); // 原数据不应被副本修改
console.assert(copy.self === copy); // 循环引用仍指向副本自身

这段代码的关键不是“复制了几层”，而是结构化克隆会维护已经访问过的引用关系。因此，嵌套数组和 Map 不再与原对象共享引用，循环引用也不会因为递归回到根节点而失控。

为什么有些值会让 structuredClone 抛异常

如果调用直接抛出 DataCloneError，优先把输入拆成最小成员。结构化克隆算法不能复制函数和 DOM 节点；另外，普通对象的原型链、属性描述符、getter/setter 等元数据也不会按原样复刻，正则的 lastIndex 也不应作为复制后的状态依据。

// 用最小输入定位不可克隆成员，捕获异常后保留原始错误信息
function clonePayload(payload) {
  try {
    return structuredClone(payload);
  } catch (error) {
    if (error.name === "DataCloneError") {
      // 这里应记录字段路径，方便从大对象中移除函数或 DOM 节点
      console.error("存在不可结构化克隆的成员", error.message);
    }
    throw error; // 其他异常不能被静默吞掉
  }
}

const payload = {
  title: "draft",
  format: () => "markdown", // 函数成员会触发 DataCloneError
};

clonePayload(payload);

排查时可以先复制纯数据字段，再逐个加入复杂成员。若业务对象来自类实例，不要只因为调用没有报错就认为实例行为完整保留；需要传递的是数据时，可以显式转换成普通对象，并在接收端重新建立方法和原型。

使用 transfer 时别把“搬走”写成“复制”

structuredClone(value, { transfer: [buffer] }) 可以把可转移对象交给新对象，而不是复制底层资源。以 ArrayBuffer 为例，转移完成后原对象中的 buffer 会被分离，后续不能继续按原来的方式使用。

// 只在明确要交出底层缓冲区所有权时使用 transfer
const buffer = new ArrayBuffer(8);
const source = { buffer };

const moved = structuredClone(source, {
  transfer: [buffer], // 资源转移给 moved，不是再复制一份
});

console.log(moved.buffer.byteLength); // 新对象持有可用缓冲区
console.log(source.buffer.byteLength); // 原对象中的缓冲区已被分离

如果只是想让两个对象各自保留数据，应省略 transfer，让结构化克隆执行普通复制。转移适合明确的所有权交接，例如把大块二进制数据交给另一个执行上下文；它不适合作为“让拷贝更安全”的默认开关。

最后用这张排查清单收口

浏览器端可先做能力检测，再决定是否使用降级方案。MDN 将 structuredClone() 标为广泛可用，并说明现代浏览器自 2022 年 3 月起已普遍支持；如果项目仍需覆盖更早环境，降级逻辑必须服从数据类型契约。

// 能力检测只负责判断 API 是否存在，不代表输入一定可克隆
function copyData(value) {
  if (typeof structuredClone === "function") {
    return structuredClone(value);
  }

  // 只有确认数据是 JSON 子集时，才考虑项目自己的降级方案
  return JSON.parse(JSON.stringify(value));
}

上线前可以按下面顺序复查：

1. 数据是否包含函数、DOM 节点、Symbol 或带特殊行为的类实例？
2. 是否需要保留原型、getter/setter、属性描述符或正则的 lastIndex？如果需要，重新设计数据传输边界。
3. 是否只是普通拷贝？若是，不要加入 transfer；若要转移，明确记录原对象何时失效。
4. 是否为旧浏览器准备了与业务数据类型匹配的降级路径？JSON 方案不能处理循环引用、Map、Set 和很多特殊值。

常见问题

structuredClone 能复制循环引用吗？

可以。结构化克隆会记录已经访问过的引用，循环引用会在副本中保持对应关系。

为什么复制函数会报 DataCloneError？

函数不能被结构化克隆。可以先把函数从数据对象中移出，传递纯数据，再在接收端绑定行为。

structuredClone 和 JSON 深拷贝怎么选？

普通结构化数据优先考虑 structuredClone。JSON 往返只适合已经确认属于 JSON 子集的数据，不能把它当作通用深拷贝。