Skip to content
FEE
Frontend Engineering Essentials
Hardened· 2026-07

[FEE-404] 儲存與狀態持久化 ​

INFO

瀏覽器提供了多種儲存 API,各自針對不同的使用情境進行最佳化:Cookie 隨每個 HTTP 請求傳送、Web Storage 提供簡單的鍵值持久化、IndexedDB 處理結構化與大規模資料、Cache API 儲存 HTTP 請求/回應對以供離線使用,而 File System Access API 則提供直接的檔案讀寫存取。選擇正確的 API,是建構可靠持久化狀態應用程式的關鍵。理解每個 API 的安全邊界同樣重要,因為選錯 API 可能讓敏感資料外洩給攻擊者。

背景 ​

使用者填寫多步驟表單時,不小心在第三步關閉了瀏覽器分頁。回來之後,表單內容全空了。資料必須在關閉分頁後依然存在,但登出後就該清除:localStorage 跨 session 持久化、sessionStorage 在分頁關閉時清除,而 IndexedDB 則處理大小超過鍵值儲存上限的結構化資料。選用哪種儲存 API,取決於資料的生命週期、大小與結構,也取決於這份資料是否需要在多個分頁間存取。

客戶端儲存從單一機制(1994 年引入的 Cookie)演進至如今豐富的專用 API 生態系。每一代都解決了前一代的限制:

Cookie 設計用於伺服器往返狀態:Session 識別碼、CSRF token、同意旗標。它們會自動附加到每個與其 domain 和 path 匹配的 HTTP 請求中,這使得它們特別適合驗證用途,但不適合作為通用儲存。每個 Cookie 約 4 KB 的限制和同步的 document.cookie 字串 API 強化了這個狹隘的範疇。

Web Storage(localStorage 和 sessionStorage)隨 HTML5 而來,提供同步的鍵值字串儲存。localStorage 跨瀏覽器 session 持久化;sessionStorage 僅限於單一分頁,分頁關閉時即清除。每個 origin 約 5 MB 的限制和僅支援字串值,使其適合偏好設定和小型 UI 狀態,但不適合結構化資料或大型資料集。

IndexedDB 是一個交易式 (transactional)、非同步的物件儲存 (object store),支援索引 (index)、游標 (cursor) 和結構化複製 (structured cloning)(直接儲存物件、陣列、Blob 和 ArrayBuffer)。它的容量受下方所述的共享 origin 儲存配額限制,在現代裝置上通常可達數十 GB,而非一個固定的小上限,是任何結構化或大規模客戶端儲存的建議 API。

Cache API 儲存 Request/Response 配對,主要用於 Service Worker 離線策略。與其他 API 不同,它基於 HTTP 語意運作:你快取一個 fetch 回應,並透過匹配請求來檢索它。

File System Access API(前身為 Native File System)透過檔案和目錄選擇器對話方塊(showOpenFilePicker、showSaveFilePicker、showDirectoryPicker),提供對使用者裝置上檔案的直接讀寫存取。它是唯一能夠寫回使用者開啟的同一檔案的客戶端 API。這些選擇器方法僅限 Chromium 系列瀏覽器;Firefox 和 Safari 並未實作。Origin Private File System(OPFS,透過 navigator.storage.getDirectory() 取得)是這個 API 的跨瀏覽器子集:它讓頁面擁有一個私有、沙盒化的檔案系統,不需要選擇器對話方塊,且三大瀏覽器引擎皆支援。

儲存配額 ​

所有 origin 範圍的儲存(IndexedDB、Cache API,以及一定程度的 localStorage)共享一個配額池。navigator.storage.estimate() 方法回傳總配額和目前使用量:

js
const { quota, usage } = await navigator.storage.estimate();
console.log(`Using ${(usage / 1024 / 1024).toFixed(1)} MB of ${(quota / 1024 / 1024).toFixed(0)} MB`);

配額政策因瀏覽器而異。在 Chromium 系列瀏覽器中,無論是永久模式還是盡力而為模式,單一 origin 都可使用總磁碟空間達 60%。Firefox 的盡力而為模式是預設模式,且可能因儲存壓力被清除,它將每個群組(group)限制在總磁碟空間 10% 與 10 GiB 兩者中較小的值;群組是指一個 site,即可註冊網域(eTLD+1)及其所有子網域,因此同一個 site 上的多個 origin 會共用同一個 10 GiB 上限。Firefox 的永久模式透過 navigator.storage.persist() 取得,不受群組限制約束,改為允許單一 origin 使用總磁碟空間達 50%,上限為 8 TiB。Safari 17 及之後版本(iOS 17、iPadOS 17 與 macOS Sonoma,於 2023 年 9 月發布)允許單一 origin 使用約 60% 的總磁碟空間,裝置上所有 origin 合計的上限則為磁碟空間的 80%。更早的 Safari 版本將單一 origin 限制在初始 1 GiB,超過此上限需徵求使用者同意才能繼續成長;該提示已在 Safari 17 的變更中移除。超過配額時,IndexedDB 和 Cache API 會拋出 QuotaExceededError,localStorage 則拋出一般的 DOMException。

若要請求瀏覽器在儲存壓力下不清除你的資料,請呼叫 navigator.storage.persist():

js
const persisted = await navigator.storage.persist();
// true = 瀏覽器不會清除; false = 盡力而為 (可能被清除)

Storage Buckets API ​

navigator.storage.persist() 是一個全有全無、涵蓋整個 origin 的請求:要嘛整個 origin 都受到保護不被清除,要嘛完全不受保護。Storage Buckets API 於 Chrome 與 Edge 122(2024 年初)推出,解決了同一問題更細緻的版本。它讓一個 origin 能將其儲存空間拆分成多個具名的 bucket,各自擁有獨立的清除優先順序與持久性設定:

js
const criticalBucket = await navigator.storageBuckets.open('critical-data', {
  persisted: true,
  durability: 'strict',
});

const cacheBucket = await navigator.storageBuckets.open('disposable-cache', {
  persisted: false,
});

在儲存壓力下,瀏覽器會先清除像 disposable-cache 這類低優先順序的 bucket,才會動到 persisted: true bucket 中的資料。套用到上方的表單草稿情境,應用程式可以讓離線資源快取保持可被清除,同時確保使用者正在進行中的草稿即使在儲存壓力下也能存活。目前支援僅限 Chrome 與 Edge;Firefox 和 Safari 尚未實作此 API。

視覺對比 ​

圖表說明: x 軸代表 API 複雜度(學習曲線、所需設定)。y 軸代表儲存容量。Cookie 和 Web Storage 聚集在低複雜度、低容量的角落。IndexedDB 和 Cache API 佔據高容量、較高複雜度的區域,兩者的容量都受共享的 origin 配額限制,而非固定上限。File System Access 具有最高容量(裝置磁碟)和最高複雜度(權限提示、非同步 handle)。

範例 ​

1. localStorage 搭配跨分頁 storage 事件 ​

storage 事件會在 localStorage 變更時於其他分頁中觸發,實現簡單的跨分頁同步:

js
// 分頁 A:更新佈景主題
function setTheme(theme) {
  document.documentElement.setAttribute('data-theme', theme);
  localStorage.setItem('theme', theme);
}

// 分頁 B:監聽來自其他分頁的變更
window.addEventListener('storage', (event) => {
  if (event.key === 'theme' && event.newValue) {
    document.documentElement.setAttribute('data-theme', event.newValue);
  }
});

// 從儲存的值初始化
const savedTheme = localStorage.getItem('theme') || 'light';
setTheme(savedTheme);

注意:storage 事件僅在同一 origin 的其他分頁/視窗中觸發。它不會在進行變更的分頁中觸發。

2. IndexedDB CRUD 操作 ​

js
// 開啟(或建立)資料庫
function openDB(name, version, onUpgrade) {
  return new Promise((resolve, reject) => {
    const request = indexedDB.open(name, version);
    request.onupgradeneeded = (e) => onUpgrade(e.target.result);
    request.onsuccess = (e) => resolve(e.target.result);
    request.onerror = (e) => reject(e.target.error);
  });
}

// 使用 object store 和索引初始化資料庫
const db = await openDB('app-db', 1, (db) => {
  const store = db.createObjectStore('contacts', { keyPath: 'id', autoIncrement: true });
  store.createIndex('by_email', 'email', { unique: true });
});

// CREATE(新增)
function addContact(db, contact) {
  return new Promise((resolve, reject) => {
    const tx = db.transaction('contacts', 'readwrite');
    const store = tx.objectStore('contacts');
    const request = store.add(contact);
    request.onsuccess = () => resolve(request.result); // 回傳生成的 key
    request.onerror = () => reject(request.error);
  });
}

// READ(讀取)-- 透過索引
function getContactByEmail(db, email) {
  return new Promise((resolve, reject) => {
    const tx = db.transaction('contacts', 'readonly');
    const index = tx.objectStore('contacts').index('by_email');
    const request = index.get(email);
    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
}

// UPDATE(更新)
function updateContact(db, contact) {
  return new Promise((resolve, reject) => {
    const tx = db.transaction('contacts', 'readwrite');
    const request = tx.objectStore('contacts').put(contact); // put = upsert
    request.onsuccess = () => resolve();
    request.onerror = () => reject(request.error);
  });
}

// DELETE(刪除)
function deleteContact(db, id) {
  return new Promise((resolve, reject) => {
    const tx = db.transaction('contacts', 'readwrite');
    const request = tx.objectStore('contacts').delete(id);
    request.onsuccess = () => resolve();
    request.onerror = () => reject(request.error);
  });
}

// 使用範例
const id = await addContact(db, { name: 'Alice', email: 'alice@example.com' });
const alice = await getContactByEmail(db, 'alice@example.com');
await updateContact(db, { ...alice, name: 'Alice Wu' });
await deleteContact(db, id);

上面的範例手動將 IndexedDB 的 callback API 包裝成 Promise,以展示其底層機制。正式環境的程式碼通常會改用現成的包裝套件:idb 提供與此處相同的輕量 Promise 包裝,Dexie.js 則在其上增加更高階的查詢層。web.dev 自己的儲存指南也建議使用包裝套件,而非直接呼叫原始 API。

3. Cache API 實現離線支援 ​

js
const CACHE_NAME = 'app-shell-v1';
const PRECACHE_URLS = ['/', '/index.html', '/styles.css', '/app.js', '/logo.svg'];

// Service Worker:安裝時預快取
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => cache.addAll(PRECACHE_URLS))
  );
});

// Service Worker:從快取提供,回退到網路
self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request).then((cached) => {
      if (cached) return cached;

      return fetch(event.request).then((response) => {
        // 複製,因為 response body 只能消費一次
        const clone = response.clone();
        caches.open(CACHE_NAME).then((cache) => cache.put(event.request, clone));
        return response;
      });
    })
  );
});

// Service Worker:啟動時清除舊快取
self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((names) =>
      Promise.all(
        names
          .filter((name) => name !== CACHE_NAME)
          .map((name) => caches.delete(name))
      )
    )
  );
});

最佳實踐 ​

簡單鍵值持久化使用 localStorage;結構化或二進位資料使用 IndexedDB。 localStorage 適合儲存小型字串值,例如使用者偏好設定、功能旗標和 UI 狀態(如側邊欄的收合狀態)。物件、陣列、Blob 或大型 JSON AVOID 存入 localStorage:所需的 JSON.stringify/JSON.parse 往返是同步操作,會阻塞主執行緒。任何結構化、關聯式或二進位資料 SHOULD 使用 IndexedDB;它透過結構化複製 (structured cloning) 原生儲存物件,且完全非同步。

務必處理 QuotaExceededError。 localStorage 和 IndexedDB 在 origin 的儲存配額耗盡時都會拋出例外。儲存寫入 MUST 包裹在 try/catch 中(localStorage)或檢查交易錯誤(IndexedDB)。靜默忽略配額錯誤會造成資料遺失和應用程式崩潰。優雅降級的方式永遠優於未處理的例外:清除過時條目或通知使用者。

敏感資料 NEVER 存入 localStorage 或 sessionStorage。 在同一 origin 上執行的任何 JavaScript 都可以讀取所有 Web Storage 的值,包括透過 XSS 注入的惡意程式碼。驗證 token、API 金鑰和 session 密鑰 MUST 存放在 HttpOnly cookie 中,因為 JavaScript 完全無法存取這類 cookie。

sessionStorage 用於分頁關閉時 SHOULD 捨棄的狀態。 暫時性精靈狀態和分頁專屬的 UI 上下文適合使用 sessionStorage:它會在分頁關閉時自動清除,不需要明確的清理程式碼,也能防止過時狀態跨 session 洩漏。必須在分頁關閉後依然存在的草稿,例如上方背景段落提到的多步驟表單,則需要改用 localStorage 或 IndexedDB。

設計思維 ​

為何存在多種儲存 API ​

每個 API 針對不同的存取模式:

API設計用途傳送至伺服器?非同步?容量
Cookie伺服器往返狀態(驗證、CSRF)是,每個匹配的請求否(document.cookie 是同步的)每個 Cookie 約 4 KB
localStorage簡單的持久化 KV(偏好設定)否否(阻塞主執行緒)每個 origin 約 5 MB
sessionStorage分頁範圍的暫時 KV否否(阻塞主執行緒)每個 origin 約 5 MB
IndexedDB結構化資料、大型資料集、離線否是(交易式)Origin 配額(常為數十 GB)
Cache APIHTTP 請求/回應快取(SW)否是(Promise 式)共享 origin 配額
File System Access使用者檔案讀寫(選擇器:僅限 Chromium;OPFS:全引擎支援)否是(Promise 式)裝置磁碟

沒有單一 API 能涵蓋所有需求。Cookie 存在是因為伺服器需要在每個請求中取得狀態。localStorage 存在是因為 IndexedDB 對於佈景主題偏好來說過於複雜。Cache API 存在是因為 IndexedDB 無法原生儲存和匹配 HTTP Request/Response 配對。

框架持久化模式 ​

現代框架在這些原始 API 之上提供抽象層:

React + localStorage / useEffect。 常見模式是在 useEffect 中將狀態持久化到 localStorage,並在初始化時讀取:

js
function usePersistedState(key, defaultValue) {
  const [value, setValue] = useState(() => {
    const stored = localStorage.getItem(key);
    return stored !== null ? JSON.parse(stored) : defaultValue;
  });

  useEffect(() => {
    localStorage.setItem(key, JSON.stringify(value));
  }, [key, value]);

  return [value, setValue];
}

Vue + pinia-plugin-persistedstate。 Pinia store 可以宣告式地持久化:

js
defineStore('settings', {
  state: () => ({ theme: 'light', locale: 'en' }),
  persist: true, // 預設使用 localStorage,以 store ID 作為 key
});

Zustand persist 中介軟體。 Zustand 支援可插拔的儲存後端:

js
import { create } from 'zustand';
import { persist } from 'zustand/middleware';

const useStore = create(
  persist(
    (set) => ({ count: 0, inc: () => set((s) => ({ count: s.count + 1 })) }),
    { name: 'counter-storage' }, // localStorage key
  ),
);

SvelteKit cookies。 與 load 函式整合的伺服器端 cookie 管理:

js
// +page.server.js
export function load({ cookies }) {
  const theme = cookies.get('theme') || 'light';
  return { theme };
}

export const actions = {
  setTheme({ cookies, request }) {
    const data = await request.formData();
    cookies.set('theme', data.get('theme'), { path: '/', httpOnly: true });
  },
};

Remix cookie/session。 內建的 session 儲存,由 cookie 或外部儲存支援:

js
import { createCookieSessionStorage } from '@remix-run/node';

const { getSession, commitSession } = createCookieSessionStorage({
  cookie: { name: '__session', httpOnly: true, secure: true, sameSite: 'lax' },
});

安全考量 ​

localStorage 與 XSS。 任何透過 XSS 注入的指令碼都可以呼叫 localStorage.getItem() 並竊取所有儲存的值。透過 XSS 從 localStorage 竊取 token,是 SPA 驗證中最主要的攻擊向量。HttpOnly cookie 不受此影響,因為 JavaScript 無法存取它們。

Cookie 與 CSRF。 沒有 SameSite 屬性的 cookie 會隨跨域請求一起傳送,從而啟用 CSRF 攻擊。現代瀏覽器預設為 SameSite=Lax,但明確設定它對於縱深防禦至關重要:

SameSite 值行為
StrictCookie 永不在跨站請求中傳送
Lax在頂層導航(連結)時傳送,但不在子資源請求(圖片、frame、POST)時傳送
None在所有跨站請求中傳送(需要 Secure 旗標)

Secure 旗標。 帶有 Secure 的 cookie 僅透過 HTTPS 傳送,防止在不安全的網路上被攔截。

常見錯誤 ​

1. 在高頻路徑中同步使用 localStorage ​

localStorage.getItem() 和 localStorage.setItem() 是同步的,會阻塞主執行緒。在渲染迴圈、捲動處理器或動畫幀中呼叫它們會造成卡頓 (jank):

js
// 不佳:每次捲動事件都阻塞渲染
window.addEventListener('scroll', () => {
  localStorage.setItem('scrollY', window.scrollY);
});

// 良好:防抖並非同步寫入
let timer;
window.addEventListener('scroll', () => {
  clearTimeout(timer);
  timer = setTimeout(() => {
    localStorage.setItem('scrollY', window.scrollY);
  }, 300);
});

省略 SameSite 會允許 cookie 隨跨域請求傳送,從而啟用 CSRF 攻擊。請務必明確設定 SameSite:

Set-Cookie: session=abc123; SameSite=Lax; Secure; HttpOnly

延伸閱讀 ​

參考資料 ​