structuredclone是javascript全局函数,非html特性,仅支持chrome 98+等现代浏览器;不支持function、dom节点、undefined等,需用typeof structuredclone==='function'检测兼容性并降级。

直接用 structuredClone,别写在 HTML 标签里,也别指望它克隆 DOM 节点——它是个 JavaScript 全局函数,只管纯数据。
为什么在 HTML 中调用 structuredClone 报 “not defined”?
这不是你写法错了,是浏览器不认。Chrome 98+、Firefox 97+、Safari 15.4+、Edge 101+ 才原生支持;旧版 Safari、IE、多数安卓 WebView、Node.js(除非显式启用)都会直接抛 ReferenceError: structuredClone is not defined。
别信“加个 script 引入就能用”的说法——它不是 polyfill,不用引入任何库,但也不跨环境自动存在。
- 检查是否可用:
typeof structuredClone === 'function'是最稳妥的判断方式 - 不要只写
'structuredClone' in window:Safari 15.2 就有这个属性但内部实现有 bug(比如对1n拷贝失败) - Node.js 环境需 v17.0+ 且启用
--experimental-structured-cloning,v18.13+ 才默认开启
structuredClone 能拷贝什么?不能拷贝什么?
它按“结构化克隆算法”走,只接受可序列化的值。能处理的类型远超 JSON,但边界非常明确。
✅ 支持的典型类型:
-
Map、Set(键值/元素完整保留,顺序不变) -
Date、RegExp、Error(部分浏览器对Error支持不一) -
ArrayBuffer、TypedArray(如Uint8Array)、DataView -
Blob、File(克隆后仍可读取、上传,但URL.createObjectURL()需重调) - 循环引用对象(
a.b = a这种结构会被正确重建)
❌ 遇到这些会立刻抛 DataCloneError:
- 任何
function(包括对象方法、箭头函数、class 构造器) -
Promise、WeakMap、WeakSet -
HTMLElement、document、window、location等宿主对象 -
undefined字段({ x: undefined })、Symbol键或值 - 带 getter/setter 的属性(值不会被读取,访问器本身不执行)
如何安全地在表单状态快照中使用 structuredClone?
想保存用户输入前的状态?别碰 input 元素本身,structuredClone 不支持 DOM 节点。要克隆的是它的「可提取数据」。
- 正确做法:只传
value、checked、selectedOptions、files[0]这类原始值或实例 - 文件元数据(如 ID、标签)必须单独存,别挂载在
File实例上——克隆后自定义属性全丢 - 示例结构:
{ file: input.files[0], metadata: { id: 'upload-123' } } - 克隆后
file仍是instanceof File,可直接塞进FormData.append() - 已生成的
object URL不会被复制,要用新File再调一次URL.createObjectURL()
transfer 选项只对 ArrayBuffer 类型生效,别乱用
这个参数不是通用“加速开关”,它专为内存敏感场景设计:把底层 ArrayBuffer 的所有权从原对象转移到克隆体,避免字节复制。
- 只接受
ArrayBuffer实例数组,其他类型传进去会被忽略 - 转移后原
ArrayBuffer变成 detached(.byteLength报错),不能再读写 - 常见误用:对普通对象、Map 或 Blob 传
transfer——完全无效,也不报错,纯属白写 - 大视频帧、音频缓冲区等场景才值得用;小数据对象用默认行为更安全
真正容易被跳过的点是:它不保留原型链,class A {} 实例克隆后变成 plain Object;还有,undefined 和 function 不是“处理不好”,而是硬性拒绝——错误比 JSON 更明确,但也更难兜底。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











