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 时，可考虑采用 WXT 或 CRXJS，以获得内置的 MV3 支持、自动生成清单和现代化工具。

工作流概览

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: "..."}
Web 可访问资源	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 - 迁移后的安全审计