structuredClone 深拷貝怎麼選：DataCloneError、class 與 transfer 限制

2026-10-04

前端

JavaScript

/

/

/

/

把 JSON.parse(JSON.stringify(value)) 換成 structuredClone(value)，可以保留更多資料型別，卻不能把所有 JavaScript 物件原封不動複製。遇到 DataCloneError 或複製後的 format is not a function，先檢查資料裡是否混入函式、DOM 節點或自訂 class 行為。

structuredClone 適合建立可複製資料的獨立副本；需要保留物件行為時，應明確建立新實例。 transfer 則會讓原本的資源失效，不適合用在還要繼續讀取原資料的表單草稿。

深拷貝先確認你要保留什麼#

展開運算子 { ...value } 只建立第一層新物件，巢狀物件仍共用參照。只更新某個欄位時，可以沿修改路徑逐層建立副本，不必為整份狀態做深拷貝；但若目的是讓使用者任意編輯一份獨立草稿，則要先盤點其中的型別。

下面使用普通資料物件示範，將整段存成 .mjs 後以 Node.js 執行：

1
import assert from 'node:assert/strict';
2

3
const source = {
4
  profile: { name: '小夏' },
5
  createdAt: new Date('2026-10-04T00:00:00Z'),
6
  settings: new Map([['theme', 'dark']]),
7
  optional: undefined,
8
};
9
source.self = source;
10

11
const copy = structuredClone(source);
12
copy.profile.name = '草稿';
13
assert.equal(source.profile.name, '小夏');
14
assert.notEqual(copy.profile, source.profile);
15
assert.ok(copy.createdAt instanceof Date);
16
assert.equal(copy.createdAt.getTime(), source.createdAt.getTime());
17
assert.ok(copy.settings instanceof Map);
18
assert.equal(copy.settings.get('theme'), 'dark');
19
assert.ok(Object.hasOwn(copy, 'optional'));
20
assert.equal(copy.self, copy);
21

22
// JSON 無法直接序列化這份循環資料。
23
assert.throws(() => JSON.stringify(source), TypeError);
24
console.log('data clone checks passed');

MDN與 HTML Standard提供可複製／可轉移資料的規則。這裡檢查的是值、型別與參照關係；不能只看 console.log(copy) 外觀相似就判定成功。

DataCloneError 先找不屬於資料的成員#

任何一部分無法序列化，都可能讓整次複製失敗。函式、DOM 節點等不能直接用 structured clone 複製；若只是把 callback 與資料放進同一個物件，先拆開兩者，再複製真正需要的資料。

1
import assert from 'node:assert/strict';
2

3
assert.throws(
4
  () => structuredClone({ name: '篩選器', onSave() {} }),
5
  { name: 'DataCloneError' },
6
);
7

8
const data = { name: '篩選器', selected: ['CSS'] };
9
const actions = { onSave: (value) => value.selected.length };
10
const draft = structuredClone(data);
11
assert.equal(actions.onSave(draft), 1);

不要 catch 後直接回傳原物件，也不要偷偷改用 JSON 複製。前者重新共用巢狀參照，後者可能改掉資料型別，呼叫端卻以為拿到同樣語意的副本。若資料不能通過複製，應回報失敗或使用已定義欄位的轉換函式。

class 看似複製成功，方法卻不在了#

自訂 class 的原型鏈與 private elements 不會被複製；property descriptor、getter／setter 的描述也不會原樣保留。這些限制見 structured clone algorithm。

1
import assert from 'node:assert/strict';
2

3
class Draft {
4
  constructor(title) { this.title = title; }
5
  display() { return '草稿：' + this.title; }
6
}
7

8
const original = new Draft('複製測試');
9
const plain = structuredClone(original);
10
assert.equal(plain.title, '複製測試');
11
assert.equal(plain instanceof Draft, false);
12
assert.equal(typeof plain.display, 'undefined');
13

14
// 明確定義還原邊界：這裡只允許 title。
15
const restored = new Draft(plain.title);
16
assert.equal(restored.display(), '草稿：複製測試');

只補上 prototype 不會自動恢復 private fields、constructor 驗證或外部資源。要保留業務行為，就把可儲存資料與實例建立流程分開。若來源含 getter，也別假設讀取過程完全沒有副作用；先轉成由已知欄位組成的資料物件，再決定是否複製。

transfer 會把原 buffer 交出去#

一般複製保留來源；transfer 是移交可轉移資源。對 ArrayBuffer 而言，來源會被 detach。適用情境是你確定原路徑不再使用該 buffer，例如交給後續處理流程；不是加速所有深拷貝的通用旗標。

1
import assert from 'node:assert/strict';
2

3
const source = new Uint8Array([10, 20, 30]);
4
const copied = structuredClone(source);
5
assert.equal(source.byteLength, 3);
6
assert.notEqual(copied.buffer, source.buffer);
7

8
const moved = structuredClone(source, { transfer: [source.buffer] });
9
assert.deepEqual([...moved], [10, 20, 30]);
10
assert.equal(source.byteLength, 0);
11
assert.equal(source.buffer.byteLength, 0);