JavaScript structuredClone 复制对象时哪些值仍然不能克隆

structuredClone() 能处理普通对象、数组、Map、Set、Date、RegExp、TypedArray 和循环引用，但它复制的是“可结构化序列化的数据”，不是把 JavaScript 运行时状态完整搬过去。对象里只要嵌入一个不可序列化成员，整次调用就会抛出 DataCloneError。

排查时先把对象拆成字段：函数、DOM 节点、Symbol 值、WeakMap/WeakSet 和多数带运行时句柄的对象不要直接克隆；ArrayBuffer 则要明确自己需要“复制”还是“转移”。

先区分可克隆数据和不可克隆成员

常见的可克隆类型包括基础数值、字符串、BigInt、普通对象、数组、Map、Set、Date、RegExp、Error、ArrayBuffer、DataView 和 TypedArray。Web API 中的 Blob、File、ImageData 等类型是否可用，还取决于它们是否定义了结构化序列化规则。

真正容易踩坑的是把“数据”与“行为”混在一起。函数依赖闭包和执行环境，不能被结构化克隆；DOM 节点绑定文档树，也不能当成普通对象复制。Symbol 作为值不可序列化，WeakMap 和 WeakSet 的键关系也没有可保存的枚举数据。对象属性只要递归进入这些成员之一，外层复制也会失败。

用最小样例定位 DataCloneError

不要一上来对完整的页面状态或组件实例调用 structuredClone。先按字段缩小范围，异常信息通常只告诉你“不能克隆”，不会直接指出是哪一个属性。

function tryClone(label, value) {
  try {
    structuredClone(value);
    console.log(label, "可以克隆");
  } catch (error) {
    // DataCloneError 说明对象图中存在不可序列化成员
    console.warn(label, error.name, error.message);
  }
}

tryClone("函数", { handler: () => "ok" });
tryClone("Symbol 值", { key: Symbol("id") });
tryClone("WeakMap", new WeakMap());

// 浏览器环境中，节点属于 DOM 树，不是普通数据对象
tryClone("DOM 节点", document.createElement("div"));

实际项目可以先克隆 state.user、state.form、state.cache 等一级字段，再递归定位失败分支。修复方式通常不是“换一个深拷贝库”，而是把回调、节点、控制器等运行时对象从快照中剔除，只保留它们需要的 id、文本或配置。

理解复制成功后的语义变化

structuredClone 解决的是数据图复制，不承诺复制完整的对象行为。自定义类实例通常会得到一个普通对象形态，原型链不会按原样保留；getter、setter、只读属性等描述信息也不会成为克隆结果的一部分。RegExp 能复制，但 lastIndex 不会被保留。

这意味着“没有抛异常”不等于“业务语义完全一致”。如果类实例依赖方法、私有字段或原型上的校验逻辑，应先转成明确的 DTO，再在目标位置重新构造实例。需要保留错误类型时也应检查字段，而不要假设所有自定义属性都会原样存在。

ArrayBuffer 复制与 transfer 转移怎么选

默认调用会复制 ArrayBuffer 的数据；如果把它放进 transfer 数组，运行时会把底层数据的使用权交给克隆结果，原缓冲区随即被分离，后续不能继续按原数据读取。这适合把大块二进制数据交给 Worker 等明确的接收方，能避免不必要的复制。

const source = new ArrayBuffer(8);
new Uint8Array(source).set([1, 2, 3]);

// transfer 表示转移所有权，不是保留两份独立数据
const moved = structuredClone(source, { transfer: [source] });

console.log(moved.byteLength); // 8
console.log(source.byteLength); // 0，原 buffer 已被分离

如果发送方之后还要继续读取或重试，就不要使用 transfer；直接克隆，或在业务层重新生成一份缓冲区。transfer 列表中的对象也必须同时出现在待克隆的数据图里，否则接收方拿不到它，原对象却可能已经失去可用状态。

常见问题

structuredClone 能处理循环引用吗？

可以。算法会记录已经访问过的引用，因此自引用或互相引用的对象图不会像 JSON.stringify 那样因为循环引用直接失败。

类实例为什么能复制却不能调用原方法？

复制结果重点是可序列化的数据字段，原型链和方法不保证保留。需要实例行为时，把字段转成 DTO，克隆后再用构造函数恢复。

为什么不用 JSON.parse(JSON.stringify())？

JSON 会丢失或改写更多类型，也不能处理循环引用；structuredClone 更适合数据快照，但仍必须遵守自己的可序列化边界。