Back to liststructuredClone 与序列化边界
Site Owner
Published on 2026-05-21
详解structuredClone算法支持的类型与不支持的类型、与JSON.parse对比、递归循环引用处理及深拷贝完整方案
structuredClone 与序列化边界
结构化克隆算法支持的类型（Map/Set/Date/RegExp/ArrayBuffer/Error 等）与不支持的类型（Function/DOM 节点/Symbol/原型链）；与 JSON.parse(JSON.stringify()) 的对比；postMessage、IndexedDB、History API 中的隐式使用。
目录
- 结构化克隆算法（SCA）
- structuredClone API
- 支持 vs 不支持的类型
- 与 JSON 深拷贝的对比
- 隐式使用场景
- 深拷贝方案全景对比
- 手写验证：深拷贝边界测试
- 何时仍需手写深拷贝
- 深度追问
结构化克隆算法（SCA）
结构化克隆算法（Structured Clone Algorithm）是 HTML 规范定义的一套深拷贝标准，用于在不同上下文（Worker、IndexedDB 等）之间传递数据。
设计目标
- 支持比 JSON 更丰富的类型（循环引用、类型化数组、Date、Map 等）
- 不支持无法被序列化的类型（函数、DOM 节点）
- 正确处理循环引用（记忆已克隆节点，不无限递归）
算法核心步骤
1. 维护一个"已访问"Map：original → clone（处理循环引用）
2. 检查值类型：
- 原始值 → 直接返回
- 可克隆对象 → 创建新实例，递归克隆属性
- Transferable → 转移（不克隆）
- 不可克隆 → 抛出 DataCloneError
3. 对象属性只克隆"自有可枚举"属性（不克隆原型链方法）
structuredClone API
structuredClone() 是 Web 标准的全局函数（浏览器和 Node.js 17+ 均支持），直接使用结构化克隆算法。
const original = {
name: 'Alice',
scores: [100, 95, 88],
meta: { joined: new Date('2020-01-01') }
};
const clone = structuredClone(original);
clone.scores.push(99);
clone.meta.joined.setFullYear(2021);
console.log(original.scores.length);
console.log(original.meta.joined.getFullYear());
console.log(original === clone);
Transferable 支持
const buffer = new ArrayBuffer(1024);
const view = new Uint8Array(buffer);
view[0] = 42;
const cloned = structuredClone(
{ data: buffer, name: 'test' },
{ transfer: [buffer] }
);
console.log(buffer.byteLength);
console.log(cloned.data.byteLength);
console.log(new Uint8Array(cloned.data)[0]);
支持 vs 不支持的类型
✅ 支持克隆的类型
const testClone = structuredClone({
number: 42,
string: 'hello',
boolean: true,
null_: null,
undefined_: undefined,
bigint: 9007199254740993n,
date: new Date(),
regexp: /abc/gi,
error: new Error('test'),
map: new Map([['key', 'value']]),
set: new Set([1, 2, 3]),
mapNested: new Map([[{}, new Set([1, 2])]]),
buffer: new ArrayBuffer(8),
u8: new Uint8Array([1, 2, 3]),
f64: new Float64Array([Math.PI]),
dataView: new DataView(new ArrayBuffer(4)),
blob: new Blob(['hello']),
array: [1, [2, [3]]],
object: { a: { b: { c: 1 } } },
});
const circular = {};
circular.self = circular;
const clonedCircular = structuredClone(circular);
console.log(clonedCircular.self === clonedCircular);
❌ 不支持克隆的类型（抛出 DataCloneError）
try {
structuredClone({ fn: () => {} });
} catch (e) {
console.log(e.name);
}
try {
structuredClone(document.body);
} catch (e) {
console.log(e.name);
}
try {
structuredClone({ [Symbol('id')]: 1 });
} catch (e) {
console.log(e.name);
}
try {
structuredClone(Symbol('id'));
} catch (e) {
console.log(e.name);
}
const proxy = new Proxy({ x: 1 }, {
get(t, k) { console.log('get', k); return t[k]; }
});
const cloned = structuredClone(proxy);
try {
structuredClone(new WeakMap());
} catch (e) {
console.log(e.name);
}
⚠️ 克隆时丢失原型链
class Point {
constructor(x, y) {
this.x = x;
this.y = y;
}
distance() {
return Math.sqrt(this.x ** 2 + this.y ** 2);
}
}
const p = new Point(3, 4);
const cloned = structuredClone(p);
console.log(p.distance());
console.log(cloned.distance);
console.log(cloned instanceof Point);
console.log(Object.getPrototypeOf(cloned) === Object.prototype);
与 JSON 深拷贝的对比
全面对比表
| 特性 | structuredClone | JSON.parse(JSON.stringify()) |
|---|
| Date | ✅ 保留 Date 类型 | ❌ 变成字符串 |
| RegExp | ✅ 保留 | ❌ 变成 {} |
| Map/Set | ✅ 保留 | ❌ 变成 {} / [] |
| undefined | ✅ 保留 | ❌ 属性被删除 |
| NaN/Infinity | ✅ 保留 | ❌ 变成 null |
| 循环引用 | ✅ 支持 | ❌ 抛出错误 |
| 函数 | ❌ 抛出 DataCloneError | ❌ 属性被删除 |
| 原型链 | ❌ 丢失 | ❌ 丢失 |
| Symbol 键 | ❌ 抛出 DataCloneError | ❌ 忽略 |
| BigInt | ✅ 支持 | ❌ 抛出 TypeError |
| 性能 | 较慢（更安全） | 快（针对简单对象） |
| Error | ✅ 保留 message/stack | ❌ 变成 {} |
代码对比
const original = {
date: new Date('2024-01-15'),
regex: /hello/gi,
map: new Map([['key', 42]]),
set: new Set([1, 2, 3]),
undef: undefined,
nan: NaN,
infinity: Infinity,
fn: () => 'hello',
};
let scClone;
try {
scClone = structuredClone(original);
} catch (e) {
console.log('structuredClone 失败：', e.message);
}
const jsonClone = JSON.parse(JSON.stringify(original));
console.log({
date: jsonClone.date,
regex: jsonClone.regex,
map: jsonClone.map,
set: jsonClone.set,
undef: 'undef' in jsonClone,
nan: jsonClone.nan,
infinity: jsonClone.infinity,
fn: 'fn' in jsonClone,
});
隐式使用场景
结构化克隆在以下 API 中自动使用，开发者不需要手动调用：
1. postMessage（Web Workers）
worker.postMessage({ data: someObject });
2. IndexedDB
const store = db.transaction('items', 'readwrite').objectStore('items');
store.add({ date: new Date(), map: new Map() });
3. History API
history.pushState({ user: { id: 1 }, visited: new Date() }, '', '/page');
4. Notification API
new Notification('提醒', { data: { id: 1, tags: new Set(['urgent']) } });
5. MessageChannel
const { port1, port2 } = new MessageChannel();
port1.onmessage = ({ data }) => console.log(data);
port2.postMessage({ value: new Date() });
深拷贝方案全景对比
const json = (obj) => JSON.parse(JSON.stringify(obj));
const sc = (obj) => structuredClone(obj);
import { cloneDeep } from 'lodash-es';
function deepClone(value, seen = new WeakMap()) {
if (value === null || typeof value !== 'object' && typeof value !== 'function') {
return value;
}
if (seen.has(value)) return seen.get(value);
if (typeof value === 'function') return value;
if (value instanceof Date) return new Date(value.getTime());
if (value instanceof RegExp) return new RegExp(value.source, value.flags);
if (value instanceof Error) {
const e = new value.constructor(value.message);
e.stack = value.stack;
if (value.cause) e.cause = deepClone(value.cause, seen);
return e;
}
if (ArrayBuffer.isView(value)) {
return new value.constructor(value.buffer.slice(0));
}
if (value instanceof ArrayBuffer) return value.slice(0);
if (value instanceof Map) {
const cloned = new Map();
seen.set(value, cloned);
for (const [k, v] of value) {
cloned.set(deepClone(k, seen), deepClone(v, seen));
}
return cloned;
}
if (value instanceof Set) {
const cloned = new Set();
seen.set(value, cloned);
for (const v of value) {
cloned.add(deepClone(v, seen));
}
return cloned;
}
if (Array.isArray(value)) {
const cloned = [];
seen.set(value, cloned);
for (let i = 0; i < value.length; i++) {
cloned[i] = deepClone(value[i], seen);
}
return cloned;
}
const cloned = Object.create(Object.getPrototypeOf(value));
seen.set(value, cloned);
const ownKeys = [
...Object.getOwnPropertyNames(value),
...Object.getOwnPropertySymbols(value),
];
for (const key of ownKeys) {
const descriptor = Object.getOwnPropertyDescriptor(value, key);
if (descriptor.value !== undefined) {
Object.defineProperty(cloned, key, {
...descriptor,
value: deepClone(descriptor.value, seen),
});
} else {
Object.defineProperty(cloned, key, descriptor);
}
}
return cloned;
}
手写验证：深拷贝边界测试
function runCloneTests(cloneFn, name) {
const tests = [
{
desc: '基础对象',
input: { a: 1, b: 'hello', c: true, d: null },
check: (original, clone) => {
return JSON.stringify(original) === JSON.stringify(clone)
&& original !== clone;
},
},
{
desc: 'Date 保留类型',
input: new Date('2024-01-15'),
check: (o, c) => c instanceof Date && c.getTime() === o.getTime(),
},
{
desc: 'RegExp 保留',
input: /hello/gi,
check: (o, c) => c instanceof RegExp && c.source === o.source && c.flags === o.flags,
},
{
desc: 'Map 保留',
input: new Map([['key', 'value'], [1, { nested: true }]]),
check: (o, c) => c instanceof Map && c.size === o.size,
},
{
desc: 'Set 保留',
input: new Set([1, 2, 3, { x: 1 }]),
check: (o, c) => c instanceof Set && c.size === o.size,
},
{
desc: 'undefined 值保留',
input: { a: undefined, b: 1 },
check: (o, c) => 'a' in c && c.a === undefined,
},
{
desc: 'NaN 保留',
input: { value: NaN },
check: (o, c) => Number.isNaN(c.value),
},
{
desc: '循环引用不崩溃',
input: (() => { const o = {}; o.self = o; return o; })(),
check: (o, c) => {
try { return c.self === c; }
catch { return false; }
},
},
{
desc: '深层嵌套',
input: { a: { b: { c: { d: { e: [1, 2, 3] } } } } },
check: (o, c) => {
c.a.b.c.d.e.push(4);
return o.a.b.c.d.e.length === 3;
},
},
{
desc: 'Symbol 键',
input: (() => { const s = Symbol('id'); const o = {}; o[s] = 42; return o; })(),
check: (o, c) => {
const oKeys = Object.getOwnPropertySymbols(o);
const cKeys = Object.getOwnPropertySymbols(c);
return cKeys.length === oKeys.length;
},
},
];
console.log(`\n=== ${name} ===`);
let passed = 0;
for (const { desc, input, check } of tests) {
try {
const clone = cloneFn(input);
const ok = check(input, clone);
console.log(`${ok ? '✅' : '❌'} ${desc}`);
if (ok) passed++;
} catch (e) {
console.log(`❌ ${desc}（异常：${e.message}）`);
}
}
console.log(`通过 ${passed}/${tests.length}`);
}
runCloneTests(v => JSON.parse(JSON.stringify(v)), 'JSON 深拷贝');
runCloneTests(v => structuredClone(v), 'structuredClone');
runCloneTests(deepClone, '手写 deepClone');
何时仍需手写深拷贝
class CustomError extends Error {
constructor(msg, code) {
super(msg);
this.code = code;
}
}
const e = new CustomError('失败', 404);
const sc = structuredClone(e);
const dc = deepClone(e);
const store = {
state: { count: 0 },
increment() { this.state.count++; },
};
const storeCopy = deepClone(store);
const sym = Symbol('private');
const obj = { [sym]: 'secret', public: 'visible' };
const sc2 = structuredClone(obj);
const dc2 = deepClone(obj);
const reactive = {
_value: 0,
get value() { return this._value; },
set value(v) { this._value = v; },
};
const dc3 = deepClone(reactive);
dc3.value = 10;
深度追问
Q1：structuredClone 比 JSON.parse(JSON.stringify()) 慢多少？
通常慢 2-5 倍（取决于数据结构复杂度）。JSON 对于简单对象有 V8 的高度优化路径。但 structuredClone 在处理 ArrayBuffer、Map、Set 等场景时更优，且不存在 JSON 的语义错误（丢失 undefined、NaN 变 null 等）。
选择标准：优先使用 structuredClone，仅在性能 profiling 证明其是瓶颈，且数据满足 JSON 限制时，才降级使用 JSON 方案。
Q2：postMessage 中同时传递普通对象和 ArrayBuffer 时，各自的序列化方式？
普通对象（非 Transferable）：使用结构化克隆（深拷贝，O(n)）。ArrayBuffer 若在 transfer 列表中：使用所有权转移（O(1)，原持有方 detached）；若不在 transfer 列表：同样深拷贝。
Q3：为什么 structuredClone 不支持 Symbol 键？
Symbol 是唯一且不可复制的标识符，其语义本身就是"全局唯一"。结构化克隆的目的是在上下文间传递可重建的数据。Symbol 无法在另一个上下文中重建同一 Symbol（除非是 Symbol.for() 的全局 Symbol），因此算法选择抛出错误而非静默丢失。
Q4：history.pushState(state) 的 state 大小有限制吗？
有。规范推荐上限为 640KB，Chrome 实际实现约 2MB。且 state 使用结构化克隆序列化存储在内存中，过大的 state 会增加内存压力。建议 state 中只存 ID，真实数据存在 store 或 URL 参数中。
