前端 structuredClone 复制表单状态：对象克隆、File 数据与不可复制字段怎么排查

编辑表单要支持“取消修改”和草稿回退时，直接保存原对象很容易踩到引用共享；但把整个表单状态交给 structuredClone() 也不是万能解法。普通对象、File、ArrayBuffer 和 DOM 节点走的是不同边界，先分清对象类型，才能知道该复制、该转移，还是该把字段移出草稿。

把表单状态复制成快照时，优先让数据保持为可序列化的普通值；文件可以克隆，底层缓冲区只有在明确接受原对象失效时才放进 transfer，不可复制字段则要在进入草稿前拦截。

先从编辑草稿的引用问题开始

假设页面有一个商品编辑表单，用户修改标题和附件后点击“取消”。如果快照只是 const backup = formState，它和当前状态仍然指向同一个对象；如果只用展开运算符，嵌套的 shipping 仍会共享引用。

const formState = {
  title: "春季目录",
  shipping: { city: "杭州" },
  attachments: []
};

const draftState = structuredClone(formState);
draftState.shipping.city = "宁波";

console.log(formState.shipping.city); // 杭州
console.log(draftState.shipping.city); // 宁波

这里的验收点很简单：修改 draftState.shipping.city 后，原始 formState 仍应打印“杭州”。这就是把“可回退快照”与“当前编辑对象”分开的最小证据。

普通字段可以复制，函数和节点不能混进草稿

结构化克隆会递归复制对象，还能处理循环引用；但函数、DOM 节点以及带有不可序列化成员的对象不能直接复制。失败时浏览器抛出 DataCloneError，不是返回一个“缺少字段的半成品”。

const editor = document.querySelector("#editor");
const formState = {
  title: "春季目录",
  validate: () => true,
  editor
};

try {
  structuredClone(formState);
} catch (error) {
  console.log(error.name); // DataCloneError
}

实际项目中，校验函数应放在表单控制器里，DOM 引用应由界面层持有，草稿只保存标题、选项、文件和数字等业务值。一个实用的排查方法是逐个删除可疑字段，再重新复制；当异常消失时，最后移除的字段就是需要重构的边界。

File 可以保留，别把它误当成页面节点

上传控件产生的 File 代表用户选中的文件数据，它和 input 元素不是一回事。将 File 放进草稿并复制，通常仍能得到独立的文件对象；但页面元素、回调函数和临时预览 URL 不应作为业务快照的一部分。

const input = document.querySelector("#cover");
const file = input.files?.[0] ?? null;
const formState = { title: "春季目录", file };
const draftState = structuredClone(formState);

console.log(draftState.file instanceof File); // true
console.log(draftState.file === formState.file); // false

验收时检查两件事：复制结果仍是 File，并且不是原对象身份。真正提交时再从草稿取出文件交给 FormData；不要把 URL.createObjectURL() 返回的预览地址当成可持久化字段。

ArrayBuffer 的 transfer 是转移，不是多一份副本

图片预处理或 Worker 通信中可能会遇到 ArrayBuffer。不提供选项时，structuredClone() 会复制它；把缓冲区放进 transfer 后，资源所有权转给新对象，原对象会被分离。

const original = new Uint8Array(4);
original[0] = 7;

const moved = structuredClone(original, {
  transfer: [original.buffer]
});

console.log(moved[0]); // 7
console.log(original.byteLength); // 0

这里别急着追求“零拷贝”。如果后续代码还要读取 original，转移会让它不可用；只有确认所有调用方都切换到 moved 后，才应使用这个选项。

把复制边界固定在一个小函数里

表单状态越复杂，越不适合在页面各处随手调用克隆。可以把快照入口收拢到一个函数，先检查字段类型，再把结构化克隆失败转换成页面能理解的错误。

function cloneDraft(formState) {
  if (formState.file !== null && !(formState.file instanceof File)) {
    throw new TypeError("file must be File or null");
  }

  try {
    return structuredClone(formState);
  } catch (error) {
    if (error.name === "DataCloneError") {
      throw new TypeError("草稿包含不可复制字段");
    }
    throw error;
  }
}

这个函数的成功状态是返回一个可独立修改的草稿；失败状态则明确告诉调用方检查字段，而不是悄悄丢掉回退能力。若项目要兼容不支持 structuredClone 的旧环境，还应在应用入口做能力检测并选择经过测试的降级方案。

相关问题：复制表单状态时最容易漏掉什么

为什么 JSON.stringify 不能替代 structuredClone？

JSON 会丢失或改变部分非 JSON 类型，也不能处理循环引用；它更像传输格式，不是通用的表单快照工具。需要保留 File、日期或循环结构时，应按实际数据类型选择方案。

复制后的 File 能直接当作上传凭据吗？

不能。File 只是文件数据对象，上传仍要经过服务端鉴权、大小限制和内容校验；客户端复制成功不代表服务端会接受文件。

什么时候不该使用 transfer？

当原缓冲区还有读取者，或代码需要在转移后继续访问原对象时，不要使用。先用普通克隆验证数据路径，再根据所有权边界决定是否转移。

总结：先定义草稿字段，再选择复制方式

structuredClone() 解决的是结构化数据的深复制，不负责替你整理页面引用。把 formState 限定为可序列化业务值，单独管理 DOM、函数和预览状态；对 File 做类型验收，对 ArrayBuffer 的 transfer 做原对象失效验收，回退和提交流程就会清楚很多。