structuredclone能准确保留date、regexp、map、set、arraybuffer、blob、file、imagedata、error及bigint等类型;不支持function、promise、weakmap、weakset、proxy、dom节点和全局宿主对象,遇之抛datacloneerror。

structuredClone 能准确保留多数内置对象的类型和值,但对部分特殊内置对象有明确限制——不是“表现不稳定”,而是设计上明确不支持或有条件支持。
能正确克隆的内置对象
以下类型在调用 structuredClone 后,不仅内容被复制,类型也保持一致:
-
Date:克隆后仍是 Date 实例,
cloned instanceof Date返回true -
RegExp:正则表达式对象被完整复制(flags、source 都保留),
cloned instanceof RegExp为true -
Map / Set:键值对/元素被深拷贝,嵌套的 Map/Set 也被递归处理,
structuredClone(new Map()) instanceof Map成立 - ArrayBuffer / TypedArray:底层二进制数据被复制,新 ArrayBuffer 与原对象内存隔离
- Blob / File / ImageData(浏览器环境):作为可序列化 Web API 对象,能被克隆且保持类型
-
Error 及其子类(如 TypeError、RangeError):仅限标准错误类型;克隆后仍为对应 Error 实例,
message和name属性保留
无法克隆或会出错的内置对象
这些对象在 structuredClone 中属于“禁止列表”,尝试克隆会直接抛出 DataCloneError 或静默丢弃:
- Function:包括普通函数、箭头函数、class 方法等,一律不支持,调用即报错
- Promise:无法序列化,调用时抛错(部分旧版浏览器可能静默忽略,但行为不可靠)
- WeakMap / WeakSet:因弱引用机制与结构化克隆不兼容,直接抛错
- Proxy:代理对象内部 trap 无法重建,不支持克隆
-
DOM 节点(如
Element、Document):属于宿主对象,不在结构化克隆协议范围内,调用即报错 -
Window / globalThis 等全局宿主对象:同样不可克隆,报
DataCloneError
部分支持但需注意细节的类型
这些对象能被克隆,但某些特性会丢失或降级:
- Symbol 作为属性键:整个键值对被忽略(不报错,也不出现在克隆结果中)
- undefined 属性值:会被保留(structuredClone 支持 undefined),但 JSON 方案会丢失
-
BigInt:支持克隆,
structuredClone(123n)返回相同值的 BigInt - 自定义类实例:只拷贝可枚举自有属性,原型链和方法全部丢失,结果是普通 plain object
- 带有 getter/setter 的对象:只复制当前可枚举属性的值,访问器本身不被克隆
循环引用与嵌套内置对象的处理
structuredClone 的优势之一是能安全处理含内置对象的循环结构:
- 例如一个
Map的 value 是它自己,或Date对象被多个属性引用 —— 克隆后引用关系被完整重建 - 嵌套的
new Map([['a', new Set([1, 2])]])也能逐层深拷贝,各层类型不变 - 但若循环路径中包含不支持类型(如函数),整条路径中断,报错优先于克隆
Java免费学习笔记:立即使用
解锁 Java 大师之旅:从入门到精通的终极指南











