extension-migration

拡張機能の移行（MV2 → MV3）

🚀 Premium へアップグレード https://app.extensionbooster.net/dashboard/services/extension-ai-kit で Premium 版を入手できます。

公式の移行ガイド：https://developer.chrome.com/docs/extensions/develop/migrate

フレームワークの採用を検討してください：MV2→MV3 への移行時には、MV3 の組み込みサポート、自動マニフェスト生成、最新のツールを利用できる WXT または CRXJS の採用を検討してください。

ワークフローの概要

1. 既存の MV2 拡張機能を監査します（API、権限、バックグラウンドスクリプト）
2. manifest_version を 3 に更新します
3. バックグラウンドページをサービスワーカーに変換します
4. 非推奨の API を置き換えます（以下のクイックリファレンスを参照）
5. 権限、CSP、web_accessible_resources の形式を更新します
6. webRequest を declarativeNetRequest に移行します（ブロッキングを使用する場合）
7. リモートコードをすべてローカルにバンドルします
8. Chrome の各バージョンで、すべての機能をテストします
9. Chrome ウェブストアに提出します

主な破壊的変更

項目	MV2	MV3
バックグラウンド	background.scripts/page	background.service_worker
ブラウザーアクション	browser_action / page_action	action
ネットワークのブロッキング	webRequest (blocking)	declarativeNetRequest
スクリプトの挿入	tabs.executeScript(string)	scripting.executeScript({func/files})
リモートコード	CDN スクリプトを使用可能	ローカルへのバンドルが必要
CSP	文字列値	オブジェクト {extension_pages: "..."}
ウェブからアクセス可能	string[]	matches フィールドを持つ object[]
ホスト権限	permissions 配列内	独立した host_permissions 配列
URL ヘルパー	chrome.extension.getURL	chrome.runtime.getURL
永続ストレージ	localStorage	chrome.storage.local

移行の優先チェックリスト

• manifest_version: 3 を設定
• バックグラウンドをサービスワーカーに変換
• localStorage/sessionStorage → chrome.storage.*
• XMLHttpRequest → fetch
• setInterval/setTimeout → chrome.alarms
• browser_action/page_action → action
• tabs.executeScript → scripting.executeScript
• chrome.extension.getURL → chrome.runtime.getURL
• permissions のホストエントリー → host_permissions
• web_accessible_resources をオブジェクト形式に更新
• content_security_policy をオブジェクト形式に更新
• リモートコードがないこと（CDN スクリプト、eval、文字列形式の Function()）
• webRequest のブロッキング → declarativeNetRequest（使用している場合）

クイックリファレンス：MV2 → MV3 API マップ

chrome.extension.getURL()        → chrome.runtime.getURL()
chrome.extension.getBackgroundPage() → chrome.runtime.getBackgroundPage() [deprecated, use messaging]
chrome.tabs.executeScript()      → chrome.scripting.executeScript()
chrome.tabs.insertCSS()          → chrome.scripting.insertCSS()
chrome.browserAction.*           → chrome.action.*
chrome.pageAction.*              → chrome.action.*
webRequest (blocking)            → declarativeNetRequest
localStorage                     → chrome.storage.local
XMLHttpRequest                   → fetch()
setInterval (background)         → chrome.alarms
document/window (background)     → NOT available in service worker

マニフェストの差分

// MV2
{
  "manifest_version": 2,
  "background": { "scripts": ["bg.js"], "persistent": false },
  "browser_action": { "default_icon": "icon.png" },
  "permissions": ["webRequest", "webRequestBlocking", "https://example.com/*"],
  "content_security_policy": "script-src 'self'; object-src 'self'",
  "web_accessible_resources": ["images/*.png"]
}

// MV3
{
  "manifest_version": 3,
  "background": { "service_worker": "bg.js" },
  "action": { "default_icon": "icon.png" },
  "permissions": ["declarativeNetRequest"],
  "host_permissions": ["https://example.com/*"],
  "content_security_policy": { "extension_pages": "script-src 'self'; object-src 'self'" },
  "web_accessible_resources": [{ "resources": ["images/*.png"], "matches": ["<all_urls>"] }]
}

参考ファイル

• 破壊的変更 — 変更点のすべてを変更前／変更後のコードとともに掲載
• サービスワーカーへの移行 — バックグラウンドから SW へのガイド
• ネットワークリクエストの移行 — webRequest から declarativeNetRequest への移行
• 移行チェックリスト — テストを含むステップごとのチェックリスト

関連スキル

• extension-manifest - MV3 マニフェストの生成
• extension-testing - 移行後のテスト
• extension-security - 移行後のセキュリティ監査