structuredClone() 一行代码实现真正深拷贝,支持循环引用、保留 Date/RegExp/Map/Set 等类型,可 transfer 零拷贝 ArrayBuffer;不支持函数、Promise、DOM 节点等,需降级处理。

直接调用 structuredClone() 就行,一行代码完成真正深拷贝,无需库、不转字符串、不手动递归,现代浏览器原生支持且性能最优。
基础用法:一行搞定,类型全保留
传入任意可克隆对象,返回一个完全独立的新副本:
- 修改克隆体不会影响原始对象(包括嵌套数组、对象)
- Date、RegExp、Map、Set、ArrayBuffer、TypedArray 等类型原样保留,不是字符串或空对象
- 自动识别并正确重建循环引用结构,不会爆栈或报错
处理大二进制数据:用 transfer 零拷贝转移
对 ArrayBuffer 或 TypedArray 等大块内存,用 transfer 选项避免复制开销:
- 写法:
structuredClone(obj, { transfer: [buffer] }) - 执行后原 buffer 变为 detached(
byteLength === 0),不可再读写 - 适合向 Web Worker 传递视频帧、音频缓冲等高频大数据场景
兼容性与安全使用要点
不是所有值都能克隆,提前知道边界能避免运行时报错:
- ✅ 支持:普通对象、数组、Date、RegExp、Map、Set、Error、Blob、File、BigInt、循环引用
- ❌ 不支持:函数、Promise、WeakMap、WeakSet、DOM 节点(如 Element、document)、undefined 属性、Symbol 键、getter/setter
- 检测是否可用:
typeof structuredClone === 'function',不建议只查'structuredClone' in window
简单降级方案:兜底不崩溃
旧环境或不确定数据结构时,加一层防御性封装:
- 先尝试
structuredClone,失败则回退到JSON.parse(JSON.stringify(obj)) - 注意:JSON 方案会丢失 Date/RegExp/Map/Set 类型,仅适用于纯数据对象
- 若需更健壮降级,可用轻量 polyfill(自动检测原生支持,无依赖)

















