JavaScript原生深拷贝函数structuredClone使用指南-js教程-PHP中文网

structuredClone 能正确复制基本类型、普通对象、数组、Date、RegExp、Map、Set、ArrayBuffer 等可克隆类型，但不支持函数、Promise、DOM 节点、class 实例等，遇不支持类型会抛出 DATA_CLONE_ERR 错误。

javascript原生深拷贝函数structuredclone使用指南

structuredClone 是 JavaScript 原生提供的深拷贝方法，无需依赖第三方库，支持大多数常用数据类型，且能正确处理循环引用、Map、Set、Date、RegExp、ArrayBuffer 等对象。但它有明确的浏览器兼容性要求和可克隆类型限制，用错场景反而会报错。

哪些值能被 structuredClone 正确复制？

该函数只接受“可转移”（transferable）或“可克隆”（cloneable）的数据结构。支持的类型包括：

基本类型（string、number、boolean、null、undefined、symbol、bigint）
普通对象（plain object）和数组（Array）
Date、RegExp、Map、Set、Error（仅属性，不保留原型链和方法）
ArrayBuffer、TypedArray（如 Uint8Array）、DataView、Blob、File、ImageBitmap、ImageData
嵌套结构——只要内部所有层级都属于上述类型，就能完整深拷贝

不支持的典型例子：函数、Promise、WeakMap、WeakSet、window 对象、DOM 节点、class 实例（含自定义 getter/setter）、带不可枚举属性的对象。遇到这些会直接抛出 DATA_CLONE_ERR 错误。

怎么安全地使用 structuredClone？

推荐始终用 try/catch 包裹调用，尤其在不确定输入来源时：

function safeClone(obj) {
  try {
    return structuredClone(obj);
  } catch (err) {
    console.warn('structuredClone 失败，回退到 JSON 方案（仅限纯数据）:', err.message);
    try {
      return JSON.parse(JSON.stringify(obj));
    } catch (e) {
      throw new Error('无法深拷贝该值：不支持的类型或存在循环引用');
    }
  }
}

注意：JSON 方案仅适用于无函数、无 undefined、无 Date/RegExp/Map/Set 的纯数据对象，且会丢失类型信息（如 Date 变成字符串）。