Manifest V3 迁移清单

此页面提供了一个快速参考，可帮助您确定可能需要对 Manifest V2 扩展进行的任何更改，以便它在 Manifest V3 (MV3) 下工作。有关这些更改性质的更多描述，请参阅 MV3 迁移指南。

# API checklist

您可能需要根据 API 表面的更改进行一些更改。本节列出了这些更改。

您的清单中有主机权限(host permissions)吗？

MV3 中的主机权限是一个单独的元素；您没有在*permissions*或 optional_permissions 中指定它们。

将主机权限移动到 manifest.json 中的 host_permissions 字段中。

你在使用背景页面(background pages)吗？

后台页面(background pages)被 MV3 中的 Service Worker 替换。

• 用 manifest.json 中的 background.service_worker 替换 background.page 或 background.scripts。请注意， service_worker 字段采用字符串，而不是字符串数组。
• 从 manifest.json 中删除 background.persistent。
• 更新后台脚本(background scripts)以适应 Service Worker 执行上下文。

认识误区

Service Worker 必须在根级别(root level)注册：它们不能位于嵌套目录中。

您是否在 manifest.json 中使用 browser_action 或 page_action 属性？

这些属性在 MV3 中统一为一个属性。

• 用action替换这些属性。

您使用的是 chrome.browserAction 还是chrome.pageAction JavaScript API？

这两个等效的 API 在 MV3 中统一为一个 API

• 迁移到 chrome.action API

您当前是否使用 chrome.webRequest 的阻塞版本？

这个 API 在 MV3 中被 declarativeNetRequest 取代。

这仅适用于用户安装的扩展；强制安装的扩展（使用 ExtensionInstallForcelist 分发的扩展）。这些扩展——通常用于企业设置——仍然可以使用 chrome.webRequest 的阻止版本。

• 将请求修改逻辑迁移到 chrome.declarativeNetRequest 规则。
• 用 declarativeNetRequest 替换 webRequestBlocking 权限。
• 如果您不再需要观察网络请求，请删除 webRequest 权限。
• 删除不必要的主机权限；阻止请求或升级请求的协议不需要 declarativeNetRequest 的主机权限。

您是否在 chrome.tabs API 中使用这些scripting/CSS 方法？

在 Manifest V3 中，有几个方法从 chrome.tabs 转移到了 chrome.scripting API。

更改以下任何 MV2 调用以使用正确的 MV3 API：

您是在执行远程代码还是任意字符串？

您不能再使用 chrome.scripting.executeScript({code: '...'})、eval() 和 new Function() 执行外部逻辑。

• 将所有外部代码（JS、Wasm、CSS）移动到您的扩展包中。
• 更新脚本和样式引用以从扩展包加载资源。
• 使用 chrome.runtime.getURL() 在运行时构建资源 URL。

您是否正在执行需要 MV2 背景上下文的函数?

在 MV3 中采用 Service Worker 与 chrome.runtime.getBackgroundPage()、chrome.extension.getBackgroundPage()、chrome.extension.getExtensionTabs() 和chrome.extension.getViews() 等方法不兼容。

• 迁移到在其他上下文和后台服务工作者之间传递消息的设计。

# 安全检查表

您可能需要根据安全策略的更改进行一些更改。本节列出了这些更改。

您是否在内容脚本(content scripts)中发出 CORS 请求？

• 将这些请求移至后台服务工作者(background service worker)。

您是否在 manifest.json 中使用自定义 content_security_policy？

• 根据需要将 content_security_policy 替换为 content_security_policy.extension_pages 或 content_security_policy.sandbox。
• 如果存在，删除 script-src、worker-src、object-src 和 style-src 指令中对外部域的引用。

By.一粒技术服务