JavaScript structuredClone 如何转移 ArrayBuffer：避免大对象复制的边界与验收

前端把大块二进制数据交给 Web Worker、文件解析器或异步校验逻辑时，最容易误判的是：调用 structuredClone() 并不等于把原来的内存直接交给另一端。默认调用会产生一份独立副本；只有把 ArrayBuffer 放进 transfer 数组，所有权才会转移，原缓冲区随后不可再用。

验收 transfer 是否真的生效，不要只看返回对象能不能读取；同时检查原始 ArrayBuffer.byteLength 是否变成 0，并确认后续代码不再访问原视图。

先分清：复制数据，还是交出 ArrayBuffer

structuredClone 使用结构化克隆算法复制复杂值，能处理循环引用、TypedArray 和 ArrayBuffer。下面的第一段代码没有指定 transfer，所以 copy 与 source 互不共享底层数据：

const source = new Uint8Array([10, 20, 30]);
const copy = structuredClone(source);

source[0] = 99;
console.log(copy[0]); // 10
console.log(source.byteLength); // 3
console.log(copy.byteLength); // 3

这条路径适合两边都要继续使用数据的场景，代价是需要额外的内存和复制时间。若数据只需要从主线程交给接收方一次，就可以把底层 ArrayBuffer 放到转移清单里。

transfer 路径如何验收所有权变化

这里不直接转移 Uint8Array，而是转移它的 buffer。返回值仍然是一个新的 Uint8Array，但它所引用的底层资源已经归接收方所有。

const source = new Uint8Array([10, 20, 30]);
const moved = structuredClone(source, {
  transfer: [source.buffer],
});

console.log(moved[0]); // 10
console.log(moved.byteLength); // 3
console.log(source.byteLength); // 0

关键证据是最后一行：原视图的 byteLength 变成 0，说明它关联的缓冲区已经 detached。此时不要再把 source 放进缓存、重试队列或下一次消息中；需要继续处理时，应使用 moved。

为什么不能把 Uint8Array 直接放进 transfer

Uint8Array 是 TypedArray 视图，不是 transferable 对象。下面的写法会失败，正确的可转移资源是 view.buffer：

const view = new Uint8Array(8);

// structuredClone(view, { transfer: [view] }); // 不应这样写
const result = structuredClone(view, {
  transfer: [view.buffer],
});

把失败分支写进调用边界

转移是所有权变化，不是普通的复制选项。调用方最好把“可转移缓冲区”和“仍要保留的原数据”分开管理，不要在同一个对象里一边转移、一边继续依赖原视图。

function movePayload(view) {
  if (!(view instanceof Uint8Array)) {
    throw new TypeError("需要 Uint8Array");
  }

  const result = structuredClone(view, {
    transfer: [view.buffer],
  });

  if (view.byteLength !== 0) {
    throw new Error("transfer 验收失败");
  }
  return result;
}

如果对象里混入函数、DOM 节点或其他不可序列化成员，结构化克隆会抛出 DataCloneError。这类错误应该在调用边界被记录并返回可恢复状态，而不是把原始缓冲区先转移后才发现整个对象无法克隆。

兼容和使用边界：不要把 transfer 当成万能优化

• 两端都要读数据时使用默认克隆；转移后原缓冲区不可再访问。
• 需要跨 Worker 发送时，发送对象必须真的包含被转移的 ArrayBuffer；只把它写在 transfer 数组里而不放入数据对象，没有接收价值。
• 共享访问需求应另看 SharedArrayBuffer 和跨源隔离条件，不能用 transfer 替代共享内存设计。
• 运行在较老浏览器或非浏览器宿主时，先做能力检测，再决定使用结构化克隆或应用层序列化降级。

常见问题

structuredClone 默认会修改原来的 ArrayBuffer 吗？

不会。只有在 transfer 中列出该缓冲区时，原对象才会被 detached；默认克隆后原对象仍可访问。

转移后为什么 byteLength 是 0？

这是所有权已转移的可观察结果。原对象不再拥有底层内存，因此关联视图也不能继续读取原数据。

能不能把 Uint8Array 放进 transfer？

不能直接放。应传入 Uint8Array.buffer，然后使用返回的视图或返回对象中的缓冲区。

DataCloneError 和 transfer 失败有什么关系？

如果待克隆对象含有不可序列化成员，结构化克隆会抛出 DataCloneError。这和原缓冲区是否可转移是两个检查点，应分别处理。

小结：用一个状态断言守住转移边界

这项 API 的判断并不复杂：需要两份独立数据就默认克隆，只需要接收方继续处理就把真正的 ArrayBuffer 放进 transfer。代码验收时同时检查返回视图的数据和原缓冲区的 byteLength，再为 DataCloneError 留出失败路径，才能避免“看起来传过去了，旧代码却还在使用失效对象”的问题。