CHROME扩展开发之·迁移到 Manifest V3

最新推荐文章于 2024-07-06 15:58:03 发布

slongzhang_

最新推荐文章于 2024-07-06 15:58:03 发布

阅读量3.6k

点赞数 3

文章标签： chrome 前端

原文链接：https://developer.chrome.com/docs/extensions/mv3/intro/mv3-migration/

版权

迁移到 Manifest V3

让你朝着正确的方向前进。

发表于 2020 年 11 月 9 日，星期一 •更新于2021 年 8 月 13 日，星期五

功能概要
更新 manifest.json 文件
代码执行
- 远程托管代码
- 执行任意字符串
后台服务人员
修改网络请求
已弃用 API 的日落

本指南为开发人员提供了开始将扩展从 Manifest V2 迁移到 Manifest V3 (MV3) 所需的信息。一些扩展只需要很少的改动就可以使它们符合 MV3，而另一些扩展则需要在一定程度上重新设计。具有 MV2 经验以及正在创建新的 MV3 扩展的开发人员也可能会发现这很有帮助。有关快速参考指南，请参阅迁移清单。

Manifest V3 提供了许多反映我们平台愿景目标的改进。

# 功能概要

使用 MV3 的扩展有许多新特性和功能更改：

服务工作者替换背景页面。
现在使用新的declarativeNetRequest API处理网络请求修改。
不再允许远程托管代码；扩展只能执行包含在其包中的 JavaScript。
Promise支持已添加到许多方法中，但仍支持回调作为替代方案。（我们最终将支持对所有适当方法的承诺。）
MV3 中还引入了许多其他相对较小的功能更改。

有关这些更改的更完整说明，请参阅MV3 概述。

# 更新 manifest.json 文件

要使用 MV3 的功能，您需要先更新您的清单文件。自然地，您将清单版本更改为“3”，但您需要在清单文件中更改许多其他内容：主机权限、内容安全策略、操作声明和 Web 可访问资源。

# 清单版本

更改 manifest_version 元素的值是升级扩展的关键。这决定了您使用的是 MV2 还是 MV3 功能集：

// Manifest V2

"manifest_version": 2

// Manifest V3

"manifest_version": 3

# 主机权限

在 MV3 中，您需要将主机权限与其他权限分开指定：

// Manifest V2
"permissions": [
  "tabs",
  "bookmarks",
  "http://www.blogger.com/",
],
"optional_permissions": [
  "*://*/*",
  "unlimitedStorage"
]

// Manifest V3
"permissions": [
  "tabs",
  "bookmarks"
],
"optional_permissions": [
  "unlimitedStorage"
],
"host_permissions": [
  "http://www.blogger.com/",
  "*://*/*"
],

警告

您不必host_permissions为了注入内容脚本而声明内容脚本匹配模式。然而，他们被视为通过Chrome Web Store的审查过程中主机的权限请求。

# 内容安全政策

MV2 中将扩展的内容安全策略(CSP) 指定为字符串；在 MV3 中，它是一个对象，其成员代表替代 CSP 上下文：

// Manifest V2

"content_security_policy": "..."

// Manifest V3

"content_security_policy": {
  "extension_pages": "...",
  "sandbox": "..."
}

extension_pages：此政策涵盖您的扩展程序中的页面，包括 html 文件和 Service Worker。

这些页面类型由chrome-extension://协议提供。例如，扩展程序中的一个页面是chrome-extension://<extension-id>/foo.html.

sandbox：此政策涵盖您的扩展程序使用的任何沙盒扩展程序页面。

此外，MV3 不允许对extension_pagesMV2 中允许的某些 CSP 修改进行修改。的script-src, object-src，并且worker-src指示只能有以下值：

self
none
任何本地主机源、( http://localhost、http://127.0.0.1或这些域上的任何端口)

CSP 修改sandbox没有这样的新限制。

# 动作API统一

在 MV2 中，有两种不同的 API 来实现操作：browser_action和page_action. 这些 API 在引入时扮演了不同的角色，但随着时间的推移，它们变得多余，因此在 MV3 中我们将它们统一为单个actionAPI：

// Manifest V2

// manifest.json
{
  "browser_action": { … },
  "page_action": { … }
}

// background.js
chrome.browserAction.onClicked.addListener(tab => { … });
chrome.pageAction.onClicked.addListener(tab => { … });

// Manifest V3

// manifest.json
{
  "action": { … }
}


// background.js
chrome.action.onClicked.addListener(tab => { … });

# 可通过网络访问的资源

此更改将扩展资源的访问权限限制为特定站点/扩展。您现在提供了一个对象列表，而不是提供文件列表，每个对象都可以将一组资源映射到一组 URL 或扩展 ID：

// Manifest V2

"web_accessible_resources": [
  <files>
]

// Manifest V3

"web_accessible_resources": [{
  "resources": [<resources>],
  "matches": [<urls>],
  "extension_ids": [<keys>],
  optional "use_dynamic_url": boolean
}]

以前，Web 可访问资源列表适用于所有网站和扩展程序，这为指纹识别或无意的资源访问创造了机会。更新后的 API 允许扩展更严格地控制哪些其他站点或扩展可以访问扩展资源。有关使用信息，请参阅Web 可访问资源文档。

# 代码执行

MV3 施加了新的限制，通过平台更改和策略限制的组合来限制扩展执行未经审查的 JavaScript 的能力。

许多扩展不受此更改的影响。但是，如果您的 MV2 扩展执行远程托管脚本、将代码字符串注入页面或在运行时评估字符串，则您需要在迁移到 MV3 时更新代码执行策略。

使用 Manifest V3，该executeScript()方法也移动到不同的 API。

MV2: chrome.tabs.executeScript()
MV3： chrome.scripting.executeScript()。

如果您在代码中的任何位置使用 executeScript()，则需要更新该调用以使用新 API。该insertCSS()和removeCSS()方法类似地从chrome.tabs移到chrome.scripting。

# 远程托管代码

远程托管代码是指任何未作为可加载资源包含在扩展包中的代码。例如，以下两种代码都被视为远程托管代码：

从远程服务器拉取的 JavaScript 文件
在运行时传递给 eval 的代码字符串

在 MV3 中，所有扩展的逻辑都必须与扩展捆绑在一起。您不能再加载和执行远程托管的文件。有多种替代方法可用，具体取决于您的用例和远程托管的原因。两种这样的方法是：

配置驱动的特性和逻辑——在这种方法中，你的扩展在运行时加载远程配置（例如 JSON 文件）并在本地缓存配置。然后，扩展程序使用此缓存配置来决定要启用哪些功能。

使用远程服务外部化逻辑——考虑将应用程序逻辑从扩展程序迁移到您的扩展程序可以调用的远程 Web 服务。（本质上是一种消息传递形式。）这使您能够将代码保密并按需更改代码，同时避免重新提交到 Chrome 网上应用店的额外开销。

# 执行任意字符串

在 Manifest V2 中，可以使用选项对象上的tabs.executeScript和code属性执行任意代码字符串。Manifest V3 不允许执行任意代码。为了适应这种需求，扩展开发者可以使用scripting.executeScriptAPI 来注入静态文件或函数。

静态文件注入scripting.executeScript几乎与 Tabs API 中使用的相同。旧方法只需要一个文件，而新方法现在需要一个文件数组。

// Manifest V2

// background.js
chrome.tabs.executeScript({
  file: 'content-script.js'
});

// content-script.js
alert('File test alert');

// Manifest V3

// background.js
async function getCurrentTab() {/* ... */}
let tab = await getCurrentTab();

chrome.scripting.executeScript({
  target: {tabId: tab.id},
  files: ['content-script.js']
});

// content-script.js
alert('File test alert');

如果您需要更多动态，新func属性允许您将函数作为内容脚本注入并使用该args属性传递变量。请注意，该函数不会像位于内容脚本中那样运行；相反，它的源被发送到目标选项卡并在那里运行。

// Manifest V2

// background.js
let name = 'World!';
chrome.tabs.executeScript({
  code: `alert('Hello, ${name}!')`
});

// Manifest V3

// background.js
async function getCurrentTab() {/* ... */}
let tab = await getCurrentTab();

function showAlert(givenName) {
  alert(`Hello, ${givenName}`);
}

let name = 'World';
chrome.scripting.executeScript({
  target: {tabId: tab.id},
  func: showAlert,
  args: [name],
});