JavaScript 原生提供的深拷贝 API：structuredClone

一、structuredClone 是什么？

structuredClone 是 JavaScript 原生提供的深拷贝 API，用于将一个值 完整复制为一个全新的副本，并且 不会共享任何引用。

它实现的是浏览器规范中的
👉 Structured Clone Algorithm（结构化克隆算法）

这是浏览器内部通信（如 postMessage、Web Worker）使用的同一套机制。

二、它能解决什么问题？

核心能力

• ✅ 真正的 深拷贝

• ✅ 支持 循环引用

• ✅ 不丢失常见复杂类型

• ✅ 不依赖第三方库

• ✅ 性能稳定、行为可预期

示例

const obj = { a: 1, b: { c: 2 } };
const copy = structuredClone(obj);

copy.b.c = 100;
console.log(obj.b.c); // 2

三、基本用法

最简单用法

const newValue = structuredClone(oldValue);

拷贝数组

structuredClone([1, { a: 2 }]);

拷贝带循环引用的对象

const obj = {};
obj.self = obj;

const copy = structuredClone(obj);

四、structuredClone 支持拷贝的类型（重点）

类型	是否支持
Object / Array	✅
Date	✅
Map / Set	✅
RegExp	✅
ArrayBuffer	✅
TypedArray	✅
BigInt	✅
NaN / Infinity	✅
循环引用	✅

 

五、不支持拷贝的类型（必须知道）

类型	结果
Function	❌ 抛异常
Symbol	❌
DOM 节点	❌
Vue 响应式对象（Proxy）	❌

⚠️ 所以 不要直接 clone reactive() 返回的对象
应先转为普通对象。

六、与常见拷贝方案对比

1️⃣ JSON.parse(JSON.stringify)

对比项	JSON	structuredClone
深拷贝	✅	✅
Date	❌	✅
Map / Set	❌	✅
循环引用	❌	✅
稳定性	一般	⭐⭐⭐⭐⭐

---

2️⃣ lodash.cloneDeep

对比项	lodash	structuredClone
体积	大	0
依赖	有	无
规范性	自定义	浏览器标准
性能	好	更好

七、兼容性

现代浏览器均已支持：

• Chrome 98+

• Edge 98+

• Firefox 94+

• Safari 15+

兜底写法

const deepClone = (val) =>
  typeof structuredClone === 'function'
    ? structuredClone(val)
    : JSON.parse(JSON.stringify(val));

 

八、在 Vue 3 中的最佳实践（非常重要）

❌ 错误做法

 

copy.value = props.data; // 共用引用

✅ 正确做法

 

copy.value = structuredClone(props.data);

配合 watch

watch(
  () => props.data,
  (val) => {
    copy.value = structuredClone(val);
  },
  { immediate: true, deep: true }
);

九、structuredClone 的设计哲学

• 不拷贝「行为」（function）

• 只拷贝「数据」

• 保证数据结构完整性

• 保证线程 / 通信安全

---

十、一句话总结

structuredClone = 浏览器官方提供的、可靠的、支持循环引用的深拷贝方案

如果你愿意，我可以：

• 帮你判断 某个具体对象是否适合 structuredClone

• 或者写一个 Vue 项目通用的深拷贝工具函数，自动避坑