如何迁移至 Chrome 扩展程序的 Manifest V3

Avatar of Shane Duggan
Shane Duggan 发布

DigitalOcean 为您旅程的每个阶段提供云产品。立即开始使用 200 美元的免费额度!

虽然我不是一名经常编写 Chrome 扩展程序的程序员,但我肯定编写过足够的扩展程序,并且拥有足够广泛的 Web 开发经验,能够胜任这项任务。然而,就在最近,我的一位客户拒绝了我的一款扩展程序,因为我收到反馈说我的扩展程序“过时”了。

当我急于找出问题所在时,我将尴尬的情绪抛在脑后,立即开始深入研究 Chrome 扩展程序的世界。不幸的是,关于 Manifest V3 的信息很少,我很难快速理解这次迁移的意义。

不用说,由于有一份工作即将交付,我不得不费力地浏览 谷歌的 Chrome 开发者文档 并自己解决问题。虽然我完成了工作,但我不想让我在这个领域的知识和研究付诸东流,因此决定分享我希望能在我学习过程中轻松获取的信息。

为什么迁移至 Manifest 3 很重要

Manifest V3 是 Google 将在其 Chrome 浏览器中使用的 API。它是当前 API Manifest V2 的继任者,用于管理 Chrome 扩展程序如何与浏览器交互。Manifest V3 对扩展程序的规则进行了重大更改,其中一些将成为我们过去习惯使用的 V2 的新支柱。

迁移至 Manifest V3 可以概括如下

  1. 迁移自 2018 年开始。
  2. Manifest V3 将于 2023 年 1 月正式开始推出。
  3. 到 2023 年 6 月,运行 Manifest V2 的扩展程序将不再可在 Chrome 网上应用店中使用。
  4. 不符合 Manifest V3 中引入的新规则的扩展程序最终将从 Chrome 网上应用店中移除。

Manifest V3 的主要目标之一是提高用户安全性并改善整体浏览器体验。以前,许多浏览器扩展程序依赖于云端代码,这意味着 评估扩展程序是否具有风险 可能很困难。Manifest V3 旨在通过要求扩展程序包含其将运行的所有代码来解决此问题,从而允许 Google 扫描它们并检测潜在风险。它还强制扩展程序向 Google 申请更改浏览器功能的权限。

及时了解 Google 迁移至 Manifest V3 的情况非常重要,因为它引入了旨在提高用户安全性和整体浏览器体验的扩展程序新规则,不符合这些规则的扩展程序最终将从 Chrome 网上应用店中移除。

简而言之,如果您在未来几个月内不进行迁移,那么您在创建使用 Manifest V2 的扩展程序方面所做的所有努力都可能付诸东流。

2023年1月2023年6月2024年1月
Chrome 的 Canary、Dev 和 Beta 渠道将停止支持 Manifest V2 扩展程序。Chrome 网上应用店将不再允许发布可见性设置为“公开”的 Manifest V2 扩展程序。Chrome 网上应用店将删除所有剩余的 Manifest V2 扩展程序。
Chrome 网上应用店将要求使用 Manifest V3 才能获得特色徽章。已发布且公开可见的现有 Manifest V2 扩展程序将变为未列出。所有 Chrome 渠道(包括稳定渠道)将停止支持 Manifest 2,除非企业渠道得到扩展。

Manifest V2 和 V3 之间的主要区别

两者之间存在许多差异,虽然我强烈建议您阅读 Chrome 的“迁移至 Manifest V3”指南,但这里是对关键点的简短总结

  1. 在 Manifest V3 中,服务工作线程 替换了后台页面。
  2. 网络请求修改在 Manifest V3 中由新的 declarativeNetRequest API 处理。
  3. 在 Manifest V3 中,扩展程序只能执行其软件包中包含的 JavaScript 代码,不能使用远程托管的代码。
  4. Manifest V3 为许多方法引入了 promise 支持,尽管回调仍然作为替代方案受支持。
  5. 在 Manifest V3 中,主机权限是一个单独的元素,必须在 "host_permissions" 字段中指定。
  6. 在 Manifest V3 中,内容安全策略是一个对象,其成员表示替代内容安全策略 (CSP) 上下文,而不是像在 Manifest V2 中那样是一个字符串。

在一个简单的更改网页背景的 Chrome 扩展程序的清单文件中,可能如下所示

// Manifest V2
{
  "manifest_version": 2,
  "name": "Shane's Extension",
  "version": "1.0",
  "description": "A simple extension that changes the background of a webpage to Shane's face.",
  "background": {
    "scripts": ["background.js"],
    "persistent": true
  },
  "browser_action": {
    "default_popup": "popup.html"
  },
  "permissions": [ "activeTab", ],
  "optional_permissions": ["<all_urls>"]
}
// Manifest V3
{
  "manifest_version": 3,
  "name": "Shane's Extension",
  "version": "1.0",
  "description": "A simple extension that changes the background of a webpage to Shane's face.",
  "background": {
    "service_worker": "background.js"
  },
  "action": {
    "default_popup": "popup.html"
  },
  "permissions": [ "activeTab", ],
  "host_permissions": [ "<all_urls>" ]
}

如果您发现上面的一些标签看起来很陌生,请继续阅读以了解您需要知道的确切内容。

如何平滑迁移至 Manifest V3

我将迁移至 Manifest V3 总结为四个关键领域。当然,虽然新的 Manifest V3 中有很多需要从旧的 Manifest V2 中实现的新功能,但在这些四个领域实施更改将使您的 Chrome 扩展程序朝着最终迁移的正确方向迈进。

四个关键领域是

  1. 更新清单文件的基本结构。
  2. 修改主机权限。
  3. 更新内容安全策略。
  4. 修改网络请求处理。

通过这四个领域,您的清单文件的基石将为迁移至 Manifest V3 做好准备。让我们详细了解每个关键方面,并看看如何才能通过这次迁移来为您的 Chrome 扩展程序做好未来准备。

更新清单文件的基本结构

更新清单文件的基本结构是迁移至 Manifest V3 的第一步。您需要做的最重要的更改是将 "manifest_version" 元素的值更改为 3,这表示您正在使用 Manifest V3 功能集。

Manifest V2 和 V3 之间的主要区别之一是在 Manifest V3 中用单个扩展程序服务工作线程替换了后台页面。您需要在 "background" 字段下注册服务工作线程,使用 "service_worker" 键并指定单个 JavaScript 文件。即使 Manifest V3 不支持多个后台脚本,您也可以选择将服务工作线程声明为 ES 模块,方法是指定 "type": "module",这允许您导入更多代码。

在 Manifest V3 中,"browser_action""page_action" 属性被统一为单个 "action" 属性。您需要在清单文件中将这些属性替换为 "action"。类似地,"chrome.browserAction""chrome.pageAction" API 在 Manifest V3 中被统一为单个“Action”API,您需要迁移到此 API。

// Manifest V2
"background": {
  "scripts": ["background.js"],
  "persistent": false
},
"browser_action": {
  "default_popup": "popup.html"
},
// Manifest V3
"background": {
  "service_worker": "background.js"
},
"action": {
  "default_popup": "popup.html"
}

总的来说,更新清单文件的基本结构是迁移至 Manifest V3 过程中的一个关键步骤,因为它允许您利用此版本 API 中引入的新功能和更改。

修改主机权限

迁移至 Manifest V3 的第二步是修改主机权限。在 Manifest V2 中,您在清单文件的 "permissions" 字段中指定主机权限。在 Manifest V3 中,主机权限是一个单独的元素,您应该在清单文件的 "host_permissions" 字段中指定它们。

以下是如何修改主机权限的示例

// Manifest V2
"permissions": [ 
  "activeTab", 
  "storage", 
  "http://www.css-tricks.com/", 
  ":///*" 
]
// Manifest V3
"permissions": [ 
  "activeTab", 
  "scripting", 
  "storage"
],
"host_permissions": [
  "http://www.css-tricks.com/" 
],
"optional_host_permissions": [ 
  ":///*" 
]

更新内容安全策略

为了更新您的 Manifest V2 扩展程序的 CSP 以使其符合 Manifest V3,您需要对清单文件进行一些更改。在 Manifest V2 中,CSP 在清单文件的 "content_security_policy" 字段中指定为字符串。

在 Manifest V3 中,CSP 现在是一个对象,其不同的成员表示替代 CSP 上下文。您现在将不得不为 "content_security_policy.extension_pages""content_security_policy.sandbox" 指定单独的字段,而不是单个 "content_security_policy" 字段,具体取决于您使用的扩展程序页面的类型。

如果您在 "script-src""worker-src""object-src""style-src" 指令中引用了外部域名,则也应将其删除。进行这些 CSP 更新以确保扩展程序在 Manifest V3 中的安全性和稳定性非常重要。

// Manifest V2
"content_security_policy": "script-src 'self' https://css-tricks.org.cn; object-src 'self'"
// Manfiest V3
"content_security_policy.extension_pages": "script-src 'self' https://example.com; object-src
'self'",
"content_security_policy.sandbox": "script-src 'self' https://css-tricks.org.cn; object-src 'self'"

修改您的网络请求处理

迁移到 Manifest V3 的最后一步是修改您的网络请求处理。在 Manifest V2 中,您会使用 chrome.webRequest API 来修改网络请求。但是,此 API 在 Manifest V3 中被 declarativeNetRequest API 替换。

要使用此新 API,您需要在清单文件中指定 declarativeNetRequest 权限,并将代码更新为使用新 API。这两个 API 之间的一个关键区别在于,declarativeNetRequest API 要求您指定要阻止的预定地址列表,而不是像使用 chrome.webRequest API 那样能够阻止整个 HTTP 请求类别。

在您的代码中进行这些更改非常重要,以确保您的扩展程序在 Manifest V3 下继续正常运行。以下是如何修改清单文件以在 Manifest V3 中使用 declarativeNetRequest API 的示例。

// Manifest V2
"permissions": [
  "webRequest",
  "webRequestBlocking"
]
// Manifest V3
"permissions": [
  "declarativeNetRequest"
]

您还需要更新扩展程序代码以使用 declarativeNetRequest API 代替 chrome.webRequest API。

您需要检查的其他方面

我所介绍的仅仅是冰山一角。当然,如果我想涵盖所有内容,我可能需要在这里待上几天,而且让 Google 的 Chrome 开发人员指南变得毫无意义。虽然我所介绍的内容将使您具备足够的未来保障,以便在这次转换中为您的 Chrome 扩展程序做好准备,但以下是一些您可能想要查看的其他事项,以确保您的扩展程序能够发挥最佳性能。

  • 将后台脚本迁移到服务工作线程执行上下文:如前所述,Manifest V3 使用单个扩展程序服务工作线程替换后台页面,因此可能需要更新后台脚本以适应服务工作线程执行上下文。
  • 统一 **chrome.browserAction** **chrome.pageAction** API:这两个等效的 API 在 Manifest V3 中统一为单个 API,因此可能需要迁移到 Action API。
  • 迁移期望 Manifest V2 后台上下文的函数:Manifest V3 中服务工作线程的采用与 chrome.runtime.getBackgroundPage()chrome.extension.getBackgroundPage()chrome.extension.getExtensionTabs()chrome.extension.getViews() 等方法不兼容。可能需要迁移到在其他上下文和后台服务工作线程之间传递消息的设计。
  • 将内容脚本中的 CORS 请求移至后台服务工作线程:为了符合 Manifest V3,可能需要将内容脚本中的 CORS 请求移至后台服务工作线程。
  • 停止执行外部代码或任意字符串:Manifest V3 不再允许使用 chrome.scripting.executeScript({code: '...'})eval()new Function() 执行外部逻辑。可能需要将所有外部代码(JavaScript、WebAssembly、CSS)移至扩展程序包中,更新脚本和样式引用以从扩展程序包加载资源,并使用 chrome.runtime.getURL() 在运行时构建资源 URL。
  • 更新 Tabs API 中某些脚本和 CSS 方法:如前所述,一些方法在 Manifest V3 中从 Tabs API 移至 Scripting API。可能需要更新对这些方法的任何调用,以使用正确的 Manifest V3 API。

还有更多!

请花一些时间了解所有更改。毕竟,这个变化是不可避免的,如果您不希望您的 Manifest V2 扩展程序由于避免此转换而丢失,那么请花一些时间掌握必要的知识。

另一方面,如果您是 Chrome 扩展程序编程的新手并且希望开始学习,一个很好的方法是深入了解 Chrome 的 Web 开发人员工具。我通过一个关于 Linkedin Learning 的课程完成了这项工作,这让我很快掌握了相关知识。掌握了基础知识后,请返回本文并将您所了解的知识应用到 Manifest V3 中!

那么,未来我将如何使用新 Manifest V3 中的功能?

对我来说,向 Manifest V3 的过渡以及 chrome.webRequest API 的移除似乎正在将扩展程序从以数据为中心的用例(例如广告拦截器)转向更具功能性和应用性的用途。我最近一直避免应用开发,因为它有时会变得非常 资源密集。但是,这种转变可能是让我重返应用开发的原因!

近年来,人工智能工具的兴起,许多工具都提供了可用的 API,引发了大量新的和新鲜的 SaaS 应用。我个人认为,这与向更多基于应用的 Chrome 扩展程序的转变恰逢其时!虽然许多旧的扩展程序可能会在此转换中被淘汰,但大量围绕新颖 SaaS 构思构建的新扩展程序将取而代之。

因此,这是一个令人兴奋的更新,可以借此机会改进旧扩展程序或构建新扩展程序!我个人看到了在扩展程序中使用涉及人工智能的 API 来增强用户浏览体验的许多可能性。但这仅仅是冰山一角。如果您希望真正深入了解自己的专业扩展程序,或者与公司联系为他们构建/更新扩展程序,我建议您 升级您的 Gmail 帐户,以获得其在协作、开发和将扩展程序发布到 Chrome 网上应用商店方面的优势。

但是,请记住,每个开发人员的需求都不同,因此请学习您需要了解的知识,以使您当前的扩展程序保持运行,或使您的新扩展程序继续运行!