跳到主要内容
api工厂
JavaScript

structuredClone 深拷贝:与 JSON.parse(JSON.stringify()) 的差异和局限

api工厂资讯栏目 约 7 分钟阅读
本文由 AI 辅助生成,内容基于公开资讯整理改写,技术细节以官方文档为准。

结论先行:structuredClone 是浏览器与 Node.js 17+ 原生的深拷贝 API,能正确处理循环引用、Date、Map、Set、RegExp、ArrayBuffer 等 JSON 方案搞不定的类型,且不会像 JSON.parse(JSON.stringify()) 那样静默丢数据。但它不能克隆函数、DOM 节点、Symbol 键与原型链,遇到这些会抛 DataCloneError。本文用对照表和示例讲清两者的差异、局限与选型策略。

JSON 方案的七宗罪

JSON.parse(JSON.stringify(obj)) 流传最广,问题也最多:undefined、函数、Symbol 键被直接丢弃;Date 变成字符串;NaN 与 Infinity 变成 null;Map、Set、RegExp 变成空对象;BigInt 直接抛 TypeError;循环引用抛错;toJSON 钩子会被意外触发。最危险的是「静默丢失」——代码不报错,数据悄悄变了形,等发现时已经污染了存储。

js
const src = { when: new Date(), tags: new Set(['a']), skip: undefined };
const bad = JSON.parse(JSON.stringify(src));
console.log(typeof bad.when); // 'string',Date 没了
console.log(bad.tags); // {},Set 没了
console.log('skip' in bad); // false,键被丢弃

structuredClone 的正确表现

structuredClone 使用与 postMessage 相同的结构化克隆算法,上述类型全部保真,循环引用也能处理:

js
const src = { when: new Date(), tags: new Set(['a']), skip: undefined };
const good = structuredClone(src);
console.log(good.when instanceof Date); // true
console.log(good.tags instanceof Set); // true
console.log('skip' in good); // true,值为 undefined

const loop = { name: 'root' };
loop.self = loop;
const cloned = structuredClone(loop);
console.log(cloned.self === cloned); // true,循环结构保留
类型JSON 方案structuredClone
Date变字符串保真
Map / Set变空对象保真
RegExp变空对象保真
undefined 键丢弃保留
NaN / Infinity变 null保真
BigInt抛错保真
循环引用抛错支持
ArrayBuffer变空对象克隆(可转移)
函数 / DOM丢弃 / 抛错抛 DataCloneError

局限:哪些东西克隆不了

结构化克隆的设计目标是「跨线程传输数据」,不是「复制任意对象」。四类常见失败:函数(包括类方法)、DOM 节点、Symbol 作为键的属性、Error 的部分子类在旧实现中的差异。另外两个隐性行为要记住:原型链丢失——克隆 class 实例得到的是普通对象,instanceof 原类为 false,getter 会被求值成普通数据属性;属性描述符(不可写、不可枚举)不保留。

js
class User {
  constructor(name) { this.name = name; }
  hello() { return 'hi ' + this.name; }
}
const u = structuredClone(new User('ann'));
console.log(u instanceof User); // false
console.log(typeof u.hello); // 'undefined'

需要保留类行为时,应自定义 clone 方法或重建实例,而不是指望通用深拷贝。

性能与转移选项

structuredClone 是同步递归复制,超大对象(几十 MB 的嵌套结构)依然会卡主线程,此时应考虑 Worker 加转移。对 ArrayBuffer 与 TypedArray,它支持第二参数转移所有权,避免复制:

js
const buf = new ArrayBuffer(1024);
const moved = structuredClone({ buf }, { transfer: [buf] });
console.log(buf.byteLength); // 0,原 buffer 已 detach

小对象场景两者性能差距不大,选型依据应是「类型保真」而不是速度。兼容性方面,主流浏览器自 2022 年起陆续支持,Node.js 17 起全局可用,旧环境可用 core-js polyfill。

结合业务:接口数据的安全副本

前端拿到接口数据后经常要「改一份、留一份」:编辑表单改草稿、列表本地排序不污染原始缓存。用 api工厂(https://www.it120.cc/)SDK 拉取的商品详情里可能含 Date 化的时间字段与嵌套规格 Map,JSON 方案会悄悄变形,structuredClone 是更稳的默认选择:

js
import WXAPI from 'apifm-wxapi';
WXAPI.init('your-subdomain');

const res = await WXAPI.goodsDetail(id);
if (res.code === 0) {
  const origin = res.data;
  const draft = structuredClone(origin);
  draft.basicInfo.name = '新名称'; // 不影响 origin
}

SDK 返回的纯 JSON 数据本身不含函数与 DOM,正好落在 structuredClone 的能力范围内;若你在数据上挂了本地方法或响应式代理,先剥离再克隆。SDK 文档(https://www.it120.cc/sdk/index.html)列出了各端方法签名,Vue/Web 端对应 apifm-webapi。

小结

默认深拷贝选 structuredClone:类型保真、支持循环引用、原生零依赖。记住三条边界——函数与 DOM 会抛错、原型链不保留、超大对象考虑转移。JSON 方案只适合「确定是纯 JSON 且想顺便序列化」的场景,别再把它当通用深拷贝。

文章标签

JavaScript深拷贝structuredClone数据处理前端基础

相关产品

api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。