前端 structuredClone 怎样处理嵌套可转移对象

嵌套对象里的 ArrayBuffer 可以被 structuredClone 转移，关键不是嵌套深度，而是 transfer 列表是否明确包含那块缓冲区。TypedArray 是视图，不应直接放进转移列表；同一缓冲区被多个视图引用时，只列一次。调用成功后，原缓冲区会分离，相关旧视图不再是可继续使用的数据入口。

下面从“克隆以后旧数组怎么不能用了”的现象拆开排查。示例只讨论普通 ArrayBuffer、Uint8Array 和普通元数据，不涉及 SharedArrayBuffer，也不把克隆调用说成线程调度。规范地址：https://html.spec.whatwg.org/multipage/structured-data.html#structured-cloning

先找出视图背后的同一块缓冲区

设一个缩略图任务包含 meta 和 payload，payload 内有 header、body 两个视图。它们偏移和长度不同，但 buffer 属性指向同一个 24 字节 ArrayBuffer。排查时先看 buffer 对象身份，不能看到两个视图就认定有两块可以独立交出的内存。

// 两个视图共用一块缓冲区，嵌套层级不改变这种引用关系
function makePacket() {
  const buffer = new ArrayBuffer(24);
  const header = new Uint8Array(buffer, 0, 8);
  const body = new Uint8Array(buffer, 8, 16);
  header[0] = 12;
  body[0] = 73;
  return {
    meta: {kind: "thumbnail", revision: 2},
    payload: {header, body}
  };
}
if (typeof globalThis.structuredClone !== "function") {
  throw new Error("当前环境不支持 structuredClone");
}

body 只覆盖其中 16 字节，不意味着转移它的 buffer 就只交出这 16 字节。转移以底层资源为单位；同一块缓冲区的其他视图也受影响。若只允许交出一个片段，应先明确复制出独立缓冲区，再转移独立资源，这有额外复制成本。

用普通克隆建立可比较的基线

先不用 transfer，观察普通克隆的预期关系：源对象仍可用，副本拥有独立的普通 ArrayBuffer，但副本内部原本共享同一缓冲区的两个视图，仍应指向副本中的同一块缓冲区。重点是“源与副本分离”和“副本内部关系保留”同时成立。

// 使用独立样本，避免与后面的转移实验互相影响
const sourceCopy = makePacket();
const copied = structuredClone(sourceCopy);
copied.payload.body[0] = 99;

// 以下断言描述预期关系，不是已经取得的运行输出
console.assert(sourceCopy.payload.body[0] === 73, "原数据应保持独立");
console.assert(copied.payload.header.buffer === copied.payload.body.buffer,
  "副本内两个视图仍共用缓冲区");
console.assert(copied.payload.body.buffer !== sourceCopy.payload.body.buffer,
  "副本与原对象不共用这块普通 ArrayBuffer");

不要为了省事用 JSON.stringify/parse 替换这个基线。这里讨论的是带缓冲区与视图的结构化数据，不是纯 JSON 字段。支持的类型、异常和循环引用规则可查 structuredClone 文档；本文断言只是供读者执行时检查，不是虚构的成功日志。

只把明确交出的缓冲区列入 transfer

确认调用方愿意交出缓冲区后，再给同样的数据结构传入 transfer。下例从已知路径取出 header.buffer 和 body.buffer，用 Set 按对象身份去重；即使两个视图覆盖不同片段，它们的底层对象相同也只能出现一次。

// 只根据已知业务结构收集，按缓冲区对象身份去重
const sourceMove = makePacket();
const buffers = [...new Set([
  sourceMove.payload.header.buffer,
  sourceMove.payload.body.buffer
])];
const oldBuffer = sourceMove.payload.body.buffer;

const moved = structuredClone(sourceMove, {transfer: buffers});
// 从此业务应使用 moved，不再读写 sourceMove 的旧视图
console.assert(oldBuffer.byteLength === 0, "原缓冲区应已分离");
console.assert(moved.payload.header.buffer === moved.payload.body.buffer,
  "目标视图应继续共用一块缓冲区");
console.assert(moved.payload.body.byteOffset === 8, "保留视图偏移");
console.assert(moved.payload.body[0] === 73, "目标数据应可读取");
console.assert(moved.meta !== sourceMove.meta, "普通元数据仍是克隆");

这里 sourceMove 仍是一个普通对象，meta 也没有凭空消失；失去资源的是原 ArrayBuffer 及依赖它的旧视图。moved 中的普通元数据是克隆，缓冲区资源则采用转移语义，不能把整棵对象树笼统描述成“全部移动”或“全部共享”。

transfer 不是自动收集器：资源可以位于很深的嵌套路径，但应通过输入值可达，返回对象才能把它作为数据的一部分使用。不要把与输入无关的缓冲区放入列表，误以为它会自动成为返回值的新字段。关于视图与缓冲区的区别，见 可转移对象说明。

转移完成后重新梳理引用归属

“所有权”在这里是资源可用性的工程表达，不是说整个 JavaScript 对象都被销毁。成功转移后应更新业务状态指向 moved，并清理缓存、闭包或其他模块中的旧视图引用。旧引用还存在，不代表底层资源还能使用。

本例固定长度、非空的缓冲区，转移后 oldBuffer.byteLength 预期为 0；不要把“任意缓冲区长度为 0”写成通用分离检测，因为合法的零长度缓冲区也可能存在。旧 TypedArray 与 DataView 的具体访问行为并不完全一样，业务上最稳妥的规则仍是停止使用旧入口，而不是依赖每种操作是否抛错。

structuredClone 仍是当前调用中的同步操作，不会因为带了 transfer 就自动进入 Worker。转移可避免对该资源按普通克隆方式复制，但不承诺整次调用没有对象构建开销，更不能凭此编造耗时提升。

按错误类型回到数据结构排查

// 每次用全新输入演示错误，不复用已经转移过的对象
const invalid = makePacket();
try {
  structuredClone(invalid, {transfer: [invalid.payload.body]});
} catch (error) {
  if (error.name !== "DataCloneError") throw error;
  console.warn("应转移视图背后的 ArrayBuffer，而非 TypedArray 本身");
}

const duplicate = makePacket();
const sharedBuffer = duplicate.payload.body.buffer;
try {
  // 两个列表项指向同一对象，属于重复转移项
  structuredClone(duplicate, {transfer: [sharedBuffer, sharedBuffer]});
} catch (error) {
  if (error.name !== "DataCloneError") throw error;
  console.warn("转移列表需要按对象身份去重");
}

重复项和分离资源的处理由 WHATWG 转移序列化规则定义。遇错不要无条件把原对象再次普通克隆当成“万能降级”：先确认具体异常、资源状态和其他转移项，再决定是否还能重建输入。需要保留原数据的业务，应在调用前就选择普通克隆。

要写一个递归收集所有 buffer 的工具吗？

不一定。盲目递归可能把别的模块仍在使用的共享底层资源也交出去。对明确的业务结构列出允许转移的路径，通常比“找到就全部转移”更容易解释。

嵌套层数很多会自动转移吗？

不会因为嵌套深就自动转移；未列入 transfer 的普通 ArrayBuffer 按克隆处理。明确清单、唯一底层资源、成功后停止旧引用，这三件事比对象有几层更重要。