Manifest V2 拡張機能は、2026 年 8 月 31 日に Chrome ウェブストアから削除されました。ユーザーが再び拡張機能を利用できるようにするには、Manifest V3 に移行してください。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

chrome.storage

更新日: 2026-09-25 robots: noindex

説明

chrome.storage API を使用して、ユーザーデータの保存、取得、変更の追跡を行います。

権限

storage

概要

Storage API は、ユーザーデータと状態を保持するための拡張機能固有の方法を提供します。ウェブプラットフォームのストレージ API（IndexedDB、Storage）に似ていますが、拡張機能のストレージニーズを満たすように設計されています。主な機能は次のとおりです。

拡張機能サービスワーカーやコンテンツスクリプトを含むすべての拡張機能コンテキストは、Storage API にアクセスできます。
JSON シリアル化可能な値は、オブジェクトプロパティとして保存されます。
Storage API は、一括読み取り / 書き込みオペレーションで非同期です。
ユーザーがキャッシュと閲覧履歴を消去しても、データは保持されます。
保存された設定は、分割シークレットモードを使用している場合でも保持されます。
エンタープライズポリシー用の読み取り専用の管理対象ストレージ領域が含まれています。

拡張機能は、一部のコンテキスト（ポップアップやその他の HTML ページ）で [Storage][mdn-storage] インターフェース（window.localStorage からアクセス可能）を使用できますが、次の理由からおすすめしません。

拡張機能の Service Worker は Storage にアクセスできません。
コンテンツスクリプトはホストページとストレージを共有します。
Storage インターフェースを使用して保存されたデータは、ユーザーが閲覧履歴を消去すると失われます。

Service Worker からウェブストレージ API から拡張機能ストレージ API にデータを移動するには:

変換ルーティンと [onMessage][on-message] ハンドラを使用して、画面外ドキュメントを作成します。
オフスクリーンドキュメントに変換ルーティンを追加します。
拡張機能の Service Worker で、chrome.storage を確認してデータを取得します。
データが見つからない場合は、オフスクリーンドキュメントを [作成][create-offscreen] し、[sendMessage()][send-message] を呼び出して変換ルーティンを開始します。
オフスクリーンドキュメントの onMessage ハンドラ内で、変換ルーチンを呼び出します。

また、拡張機能でのウェブストレージ API の動作には、いくつかのニュアンスがあります。詳しくは、[ストレージと Cookie][storage-and-cookies] の記事をご覧ください。

ストレージ領域

Storage API は、次の 4 つのバケット（「ストレージ領域」）に分かれています。

storage.local: データはローカルに保存され、拡張機能が削除されると消去されます。割り当ての上限は約 10 MB ですが、"unlimitedStorage" 権限をリクエストすることで増やすことができます。大量のデータを保存する場合は、この方法を検討してください。

storage.sync: 同期が有効になっている場合、データはユーザーがログインしている Chrome ブラウザと同期されます。無効にすると、storage.local のように動作します。ブラウザがオフラインの場合、Chrome はデータをローカルに保存し、オンラインに戻ると同期を再開します。割り当ての上限は、1 アイテムあたり約 100 KB、8 KB です。同期されたブラウザ間でユーザー設定を保持するために使用することを検討してください。

警告: ローカルストレージ領域と同期ストレージ領域は暗号化されないため、機密性の高いユーザーデータを保存しないでください。機密データを扱う場合は、session ストレージ領域を使用して、ブラウザがシャットダウンされるまで値をメモリに保持することを検討してください。

storage.session: ブラウザセッションの間、データをメモリに保持します。デフォルトでは、コンテンツスクリプトに公開されませんが、chrome.storage.session.setAccessLevel() を設定することでこの動作を変更できます。割り当ての上限は約 10 MB です。サービスワーカーの実行全体でグローバル変数を保存するために使用することを検討してください。

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 に保存します。サービスワーカーは 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);
  }
});

ストレージからの非同期プリロード

サービスワーカーは常に実行されているわけではないため、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

any 省略可

アイテムの新しい値（新しい値がある場合）。
oldValue

any 省略可

アイテムの古い値（古い値があった場合）。

プロパティ

local

local ストレージ領域内のアイテムは、各マシンに対してローカルです。

タイプ

StorageArea & object

プロパティ

QUOTA_BYTES

10485760

ローカルストレージに保存できるデータの最大量（バイト単位）。すべての値の JSON 文字列化とすべてのキーの長さを加算して測定されます。拡張機能に unlimitedStorage 権限がある場合、この値は無視されます。この上限を超える更新はすぐに失敗し、コールバックを使用している場合は runtime.lastError が設定され、async/await を使用している場合は拒否された Promise が設定されます。

managed

managed ストレージ領域のアイテムは、ドメイン管理者が構成したエンタープライズポリシーによって設定され、拡張機能に対しては読み取り専用です。この名前空間を変更しようとすると、エラーが発生します。ポリシーの構成については、ストレージ領域のマニフェストをご覧ください。

タイプ

StorageArea

sync

sync ストレージ領域内のアイテムは、Chrome 同期を使用して同期されます。

タイプ

StorageArea & object

プロパティ

MAX_ITEMS

512

同期ストレージに保存できるアイテムの最大数。この上限を超える更新はすぐに失敗し、コールバックの使用時または Promise の拒否時に runtime.lastError が設定されます。
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

1,000,000

非推奨

storage.sync API には、持続的な書き込みオペレーションの割り当てがなくなりました。
MAX_WRITE_OPERATIONS_PER_HOUR

1800

1 時間に実行できる set、remove、clear オペレーションの最大数。これは 2 秒に 1 回で、短期間の 1 分あたりの書き込み数の上限よりも低い上限です。

この上限を超える更新はすぐに失敗し、コールバックの使用時または Promise の拒否時に runtime.lastError が設定されます。
MAX_WRITE_OPERATIONS_PER_MINUTE

120

1 分間に実行できる set、remove、clear オペレーションの最大数。これは 1 秒あたり 2 回に相当し、1 時間あたりの書き込み回数よりも短い期間で高いスループットを実現します。

この上限を超える更新はすぐに失敗し、コールバックの使用時または Promise の拒否時に runtime.lastError が設定されます。
QUOTA_BYTES

102400

同期ストレージに保存できるデータの最大合計量（バイト単位）。すべての値の JSON 文字列化とすべてのキーの長さを加えた値で測定されます。この上限を超える更新はすぐに失敗し、コールバックの使用時または Promise の拒否時に runtime.lastError が設定されます。
QUOTA_BYTES_PER_ITEM

8,192

同期ストレージ内の各アイテムの最大サイズ（バイト単位）。値の JSON 文字列化とキーの長さを加えた値で測定されます。この上限を超えるアイテムを含む更新はすぐに失敗し、コールバックの使用時または Promise の拒否時に runtime.lastError が設定されます。

イベント

onChanged

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

1 つ以上のアイテムが変更されたときに呼び出されます。

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(changes: object, areaName: string) => void
```
- 変更
  
  オブジェクト
- areaName
  
  文字列

chrome.storage コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

説明

権限

概要

ストレージ領域

マニフェスト

用途

storage.local

storage.sync

storage.session

ストレージとスロットリングの上限

ユースケース

ストレージの更新に対する同期レスポンス

ストレージからの非同期プリロード

拡張機能の例

型

AccessLevel

列挙型

StorageChange

プロパティ

プロパティ

local

タイプ

プロパティ

managed

タイプ

sync

タイプ

プロパティ

イベント

onChanged

パラメータ

chrome.storage