chrome.storage

refresh date: 2026-09-25 robots: noindex

說明

使用 chrome.storage API 儲存、擷取及追蹤使用者資料的變更。

權限

storage

總覽

Storage API 提供擴充功能專屬的方式，可保留使用者資料和狀態。這與網頁平台的儲存空間 API (IndexedDB 和 Storage) 類似，但專為滿足擴充功能的儲存需求而設計。以下列舉幾項主要功能：

  • 所有擴充功能情境 (包括擴充功能 Service Worker 和內容指令碼) 都能存取 Storage API。
  • JSON 可序列化值會儲存為物件屬性。
  • Storage API 採用非同步方式，可執行大量讀寫作業。
  • 即使使用者清除快取和瀏覽記錄，資料仍會保留。
  • 即使使用分割無痕模式，儲存的設定仍會保留。
  • 包含企業政策專屬的唯讀受管理儲存空間。

雖然擴充功能在某些情況下 (彈出式視窗和其他 HTML 網頁) 可以使用 [Storage][mdn-storage] 介面 (可從 window.localStorage 存取)，但基於以下原因，不建議使用：

  • 擴充功能的 Service Worker 無法存取 Storage。
  • 內容指令碼會與主機網頁共用儲存空間。
  • 使用者清除瀏覽記錄時，系統會刪除透過 Storage 介面儲存的資料。

如要將資料從網路儲存空間 API 移至 Service Worker 的擴充功能儲存空間 API，請按照下列步驟操作：

  1. 使用轉換常式和 [onMessage][on-message] 處理常式建立螢幕外文件。
  2. 在螢幕外文件中新增轉換常式。
  3. 在擴充功能 Service Worker 中，檢查 chrome.storage 是否有資料。
  4. 如果找不到資料，請 [建立][create-offscreen] 螢幕外文件，並呼叫 [sendMessage()][send-message] 啟動轉換常式。
  5. 在畫面外文件的 onMessage 處理常式中，呼叫轉換常式。

此外，網頁儲存空間 API 在擴充功能中的運作方式也有一些細微差異。詳情請參閱「[儲存空間和 Cookie][storage-and-cookies]」一文。

儲存空間區域

Storage API 分為下列四個值區 (「儲存空間區域」)：

storage.local
資料會儲存在本機，並在移除擴充功能時清除。配額限制約為 10 MB，但可要求 "unlimitedStorage" 權限來提高。建議您使用這項服務儲存大量資料。
storage.sync
如果啟用同步功能，資料會同步到使用者登入的所有 Chrome 瀏覽器。如果停用，則會像 storage.local 一樣運作。瀏覽器離線時，Chrome 會將資料儲存在本機，並在重新連線後繼續同步。配額限制約為 100 KB，每個項目 8 KB。建議您使用這項功能，在同步的瀏覽器中保留使用者設定。
storage.session
在瀏覽器工作階段期間，將資料保留在記憶體中。根據預設，這項功能不會向內容指令碼公開，但您可以設定 chrome.storage.session.setAccessLevel() 來變更這項行為。配額限制約為 10 MB。建議您使用這個 API 儲存 Service Worker 執行期間的全域變數。
storage.managed
管理員可以使用結構定義和企業政策，在受管理環境中設定支援的擴充功能。這個儲存空間區域為唯讀。

資訊清單

如要使用 Storage API，請在擴充功能資訊清單中宣告 "storage" 權限。例如：

{
  "name": "My extension",
  ...
  "permissions": [
    "storage"
  ],
  ...
}

用量

以下範例示範 local、sync 和 session 儲存區：

storage.local

chrome.storage.local.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.local.get(["key"]).then((result) => {
  console.log("Value currently is " + result.key);
});

storage.sync

chrome.storage.sync.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.sync.get(["key"]).then((result) => {
  console.log("Value currently is " + result.key);
});

storage.session

chrome.storage.session.set({ key: value }).then(() => {
  console.log("Value was set");
});

chrome.storage.session.get(["key"]).then((result) => {
  console.log("Value currently is " + result.key);
});

如要進一步瞭解 managed 儲存空間，請參閱「儲存空間資訊清單」。

儲存空間和節流限制

請勿將 Storage API 視為大型卡車，將資料新增至儲存空間，就像是將東西放入管道。管道中可能已有內容，甚至可能已填滿。請一律假設從新增至儲存空間到實際記錄之間會有延遲。

如要進一步瞭解儲存空間限制，以及超出限制時會發生的情況，請參閱 sync、local 和 session 的配額資訊。

用途

以下各節將示範 Storage API 的常見用途。

同步回應儲存空間更新

如要追蹤儲存空間的變更，可以為 onChanged 事件新增事件監聽器。儲存空間有任何變更時，系統就會觸發該事件。程式碼範例會監聽下列變更：

background.js:

chrome.storage.onChanged.addListener((changes, namespace) => {
  for (let [key, { oldValue, newValue }] of Object.entries(changes)) {
    console.log(
      `Storage key "${key}" in namespace "${namespace}" changed.`,
      `Old value was "${oldValue}", new value is "${newValue}".`
    );
  }
});

我們可以進一步延伸這個概念。在本範例中，我們有一個選項頁面，可讓使用者切換「偵錯模式」(此處未顯示實作)。選項頁面會立即將新設定儲存至 storage.sync，而 Service Worker 則會使用 storage.onChanged 盡快套用設定。

options.html:

<!-- type="module" allows you to use top level await -->
<script defer src="options.js" type="module"></script>
<form id="optionsForm">
  <label for="debug">
    <input type="checkbox" name="debug" id="debug">
    Enable debug mode
  </label>
</form>

options.js:

// In-page cache of the user's options
const options = {};
const optionsForm = document.getElementById("optionsForm");

// Immediately persist options changes
optionsForm.debug.addEventListener("change", (event) => {
  options.debug = event.target.checked;
  chrome.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await chrome.storage.sync.get("options");
Object.assign(options, data.options);
optionsForm.debug.checked = Boolean(options.debug);

background.js:

function setDebugMode() { /* ... */ }

// Watch for changes to the user's options & apply them
chrome.storage.onChanged.addListener((changes, area) => {
  if (area === 'sync' && changes.options?.newValue) {
    const debugMode = Boolean(changes.options.newValue.debug);
    console.log('enable debug mode?', debugMode);
    setDebugMode(debugMode);
  }
});

從儲存空間非同步預先載入

由於 Service Worker 不一定會持續執行，Manifest V3 擴充功能有時需要先從儲存空間非同步載入資料，才能執行事件處理常式。為此，下列程式碼片段使用非同步 action.onClicked 事件處理常式，等待 storageCache 全域變數填入後，再執行邏輯。

background.js:

// Where we will expose all the data we retrieve from storage.sync.
const storageCache = { count: 0 };
// Asynchronously retrieve data from storage.sync, then cache it.
const initStorageCache = chrome.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

chrome.action.onClicked.addListener(async (tab) => {
  try {
    await initStorageCache;
  } catch (e) {
    // Handle error that occurred during storage initialization.
  }

  // Normal action handler logic.
  storageCache.count++;
  storageCache.lastTabId = tab.id;
  chrome.storage.sync.set(storageCache);
});

擴充功能範例

如要查看 Storage API 的其他試用版，請瀏覽下列任一範例：

類型

AccessLevel

Chrome 102 以上版本

儲存空間的存取層級。

列舉

"TRUSTED_CONTEXTS"
指定源自擴充功能本身的內容。

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
指定源自擴充功能外部的背景資訊。

StorageChange

屬性

  • newValue

    任意 選填

    項目的新值 (如有)。

  • oldValue

    任意 選填

    項目的舊值 (如有)。

屬性

local

local 儲存區域中的項目僅限於各部機器。

類型

StorageArea & 物件

屬性

  • QUOTA_BYTES

    10485760

    本機儲存空間可儲存的資料量上限 (以位元組為單位)，計算方式為每個值的 JSON 字串化加上每個鍵的長度。如果擴充功能具有 unlimitedStorage 權限，系統會忽略這個值。如果更新會導致超過這項限制，則會立即失敗，並在使用回呼時設定 runtime.lastError，或在使用 async/await 時設定遭拒的 Promise。

managed

managed 儲存區域中的項目是由網域管理員設定的企業政策所設定，且對擴充功能而言是唯讀的；嘗試修改這個命名空間會導致錯誤。如要瞭解如何設定政策，請參閱「儲存區域資訊清單」。

類型

StorageArea

sync

sync 儲存區域中的項目會透過 Chrome 同步功能進行同步。

類型

StorageArea & 物件

屬性

  • MAX_ITEMS

    512

    同步儲存空間可儲存的項目數量上限。如果更新會導致超過這項限制，系統會立即失敗，並在使用回呼或拒絕 Promise 時設定 runtime.lastError。

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    已淘汰

    storage.sync API 不再有持續寫入作業配額。

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

    每小時可執行的 set、remove 或 clear 作業數量上限。也就是每 2 秒 1 次，上限低於短期內每分鐘寫入次數較高的限制。

    如果更新會導致超過這項限制，系統會立即失敗，並在使用回呼或拒絕 Promise 時設定 runtime.lastError。

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    每分鐘可執行的 set、remove 或 clear 作業數量上限。也就是每秒 2 次，在較短時間內提供比每小時寫入次數更高的處理量。

    如果更新會導致超過這項限制，系統會立即失敗，並在使用回呼或拒絕 Promise 時設定 runtime.lastError。

  • QUOTA_BYTES

    102400

    同步儲存空間可儲存的資料總量上限 (以位元組為單位)，計算方式為每個值的 JSON 字串化加上每個鍵的長度。如果更新會導致超過這項限制，系統會立即失敗，並在使用回呼或拒絕 Promise 時設定 runtime.lastError。

  • QUOTA_BYTES_PER_ITEM

    8192

    同步儲存空間中每個項目的大小上限 (以位元組為單位)，計算方式為值的 JSON 字串化加上索引鍵長度。如果更新內容包含超過此限制的項目，則會立即失敗，並在使用回呼或 Promise 遭拒時設定 runtime.lastError。

事件

onChanged

chrome.storage.onChanged.addListener(
  callback: function,
)

一或多個項目變更時觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (changes: object, areaName: string) => void

    • 變更

      物件

    • areaName

      字串