localStorage JSON 讀寫失敗：安全 fallback 與版本檢查

2026-10-05

前端

JavaScript

/

/

/

/

偏好設定原本能從 localStorage 讀回，更新後卻讓整個頁面初始化失敗。只在 JSON.parse() 外面加 catch 還不夠：取得 storage、讀取 key、解析字串與檢查資料版本，是四個不同的步驟。

讀取失敗時先用可用的預設狀態維持畫面，寫入失敗則明確標示尚未保存。 不要在初始化 catch 裡呼叫 localStorage.clear()，也不要自動把無法辨識的舊值覆寫成預設值。本文以可丟棄的主題偏好為例；未保存的編輯草稿應另外提供匯出或復原路徑。

先確認是沒有資料，還是資料不能使用#

MDN 的 getItem() 文件說明：key 不存在時回傳 null。這和字串 'null'、空字串、損壞 JSON 不同。

1
JSON.parse('null'); // 合法 JSON，結果是 null
2
JSON.parse('');     // SyntaxError
3
JSON.parse('{');    // SyntaxError

即使解析成功，{"version":1,"theme":42} 也不能直接交給需要字串的 UI。先驗證形狀與版本，再接受資料。不要靠 JSON.parse(raw) || defaultValue 把所有情況混成一種成功結果。

MDN 的 localStorage 文件也列出存取時的 SecurityError。因此要把 window.localStorage 的取得放在 try 裡，不能先在函式外取得，再期待內部 catch 捕捉 getter 的失敗。

回傳狀態，讓畫面決定如何復原#

這份範例只接受 version 1 的主題偏好；遇到新版或不合法資料時保留原字串，不在讀取時自動遷移或刪除。getStorage 是函式，讓瀏覽器存取和測試替身走相同入口。

1
const preferenceKey = 'example:preferences';
2
const defaultPreferences = () => ({ version: 1, theme: 'system' });
3

4
function isPreferences(value) {
5
  return value !== null && typeof value === 'object' &&
6
    value.version === 1 &&
7
    ['light', 'dark', 'system'].includes(value.theme);
8
}
9

10
function loadPreferences(getStorage) {
11
  let raw;
12
  try {
13
    raw = getStorage().getItem(preferenceKey);
14
  } catch (error) {
15
    return { status: 'unavailable', value: defaultPreferences(), error };
16
  }
17
  if (raw === null) {
18
    return { status: 'missing', value: defaultPreferences() };
19
  }
20

21
  let value;
22
  try {
23
    value = JSON.parse(raw);
24
  } catch {
25
    return { status: 'invalid-json', value: defaultPreferences() };
26
  }
27
  if (!isPreferences(value)) {
28
    return { status: 'invalid-schema', value: defaultPreferences() };
29
  }
30
  return { status: 'loaded', value };
31
}
32

33
function savePreferences(getStorage, value) {
34
  if (!isPreferences(value)) {
35
    return { status: 'invalid-schema' };
36
  }
37
  // 限定輸出欄位，避免把不相關的資料一起保存。
38
  const serializable = { version: 1, theme: value.theme };
39
  try {
40
    getStorage().setItem(preferenceKey, JSON.stringify(serializable));
41
    return { status: 'saved' };
42
  } catch (error) {
43
    return { status: 'write-failed', error };
44
  }
45
}

在瀏覽器事件或 client 初始化階段使用，別放在 Astro server frontmatter 或 SSR 的模組頂層：

1
const result = loadPreferences(() => window.localStorage);
2
// 示意：把 result.value 交給你的畫面狀態；依 result.status 顯示提示。
3
const saved = savePreferences(() => window.localStorage, {
4
  version: 1, theme: 'dark',
5
});
6
// 只有 saved.status === 'saved' 才顯示「設定已保存」。

MDN 的 setItem() 列出 QuotaExceededError。上面統一回報 write-failed，呼叫端可依 error.name 提供進一步診斷，但不要把每一個寫入例外都說成容量不足。

用替身測試缺值、損壞與拒絕存取#

將函式與以下測試放在同一個 .mjs 檔案。這些 assertion 已在 Node.js v24.13.0 執行；Map 模擬 storage，沒有讀寫瀏覽器中的使用者資料。

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

3
const values = new Map();
4
const storage = {
5
  getItem: (key) => values.get(key) ?? null,
6
  setItem: (key, value) => values.set(key, String(value)),
7
};
8
const getStorage = () => storage;
9
assert.equal(loadPreferences(getStorage).status, 'missing');
10
values.set(preferenceKey, '{');
11
assert.equal(loadPreferences(getStorage).status, 'invalid-json');
12
assert.equal(values.get(preferenceKey), '{'); // 讀取沒有覆寫舊值
13
values.set(preferenceKey, '{"version":2,"theme":"dark"}');
14
assert.equal(loadPreferences(getStorage).status, 'invalid-schema');
15
values.set(preferenceKey, 'null');
16
assert.equal(loadPreferences(getStorage).status, 'invalid-schema');
17
assert.equal(savePreferences(getStorage, {
18
  version: 1, theme: 'dark',
19
}).status, 'saved');
20
assert.equal(loadPreferences(getStorage).value.theme, 'dark');
21
assert.equal(savePreferences(getStorage, {
22
  version: 1, theme: 42,
23
}).status, 'invalid-schema');
24
const denied = () => { throw new DOMException('Blocked', 'SecurityError'); };
25
assert.equal(loadPreferences(denied).status, 'unavailable');
26
assert.equal(savePreferences(denied, defaultPreferences()).status, 'write-failed');
27
const full = () => ({
28
  setItem() { throw new DOMException('Full', 'QuotaExceededError'); },
29
});
30
assert.equal(savePreferences(full, defaultPreferences()).error.name, 'QuotaExceededError');