迁移到 Manifest V3

将 Manifest V2 扩展程序转换为 Manifest V3 扩展程序的指南。

此部分可帮助您将扩展程序从 Manifest V2 升级到 Manifest V3(Chrome 扩展程序平台的最新版本)。迁移工作大致分为以下几类。为帮助您跟踪工作进度,我们提供了一份核对清单,总结了这些文档的内容。您可以通过核对清单查看相关内容,也可以深入了解相关内容。两个路径均以升级版附加信息结尾。

  • 更新清单 - manifest.json 必须特定于 V3。本部分介绍了单独可以进行的更改。系统会通过支持的代码更改来说明与代码相关的清单更改。
  • 迁移到 Service Worker - Service Worker 会替换扩展程序的后台或事件页面,以确保后台代码远离主线程,从而降低性能。此更改还需要将 DOM、窗口和某些扩展 API 调用移入屏幕外的文档中。
  • 更新 API 调用 - 某些 API 调用需要替换为更现代的等效项。
  • 替换阻止网络请求监听器 - 在 Manifest V2 中屏蔽或修改网络请求可能会显著降低性能,并导致需要过多访问敏感用户数据。借助 Declarative Net Request API,扩展程序可以使用较少的权限来屏蔽或修改 Web 内容,而不会降低性能。
  • 提高扩展程序安全性 - Manifest V3 通过多种方式提高扩展程序的安全性。除了增强的内容安全政策之外,不再支持远程托管代码和任意字符串的执行。
  • 发布扩展程序 - 本部分介绍了如何逐步发布,以确保您的 Manifest V3 扩展程序先在有限的受众群体内进行测试,从而确保其按预期运行。

我们还提供 Extension Manifest Converter。它无法为您提供一切服务,但可帮助您入门。转换器的 README 文件中介绍了工具更改的内容。

保留当前的功能集

为了降低出现意外问题或 bug 的可能性,我们建议不要在迁移时添加新功能。例如,添加需要新权限的功能可能会触发权限警告,这会导致您的扩展程序停用,直到用户接受新权限。请参阅权限警告最佳做法,了解如何在不显示警告的情况下添加权限。

Chrome 88 或更高版本通常支持 Manifest V3。更新 API 调用时,您可能会发现替换功能可能要到版本 88 之后才在 Chrome 中推出。API 参考页面包含各 API 成员的支持信息。如果您发现需要使用其中某项功能,可以在清单文件中指定最低 Chrome 版本

新的扩展程序平台功能

自 Manifest V3 发布以来,我们不断添加新功能,其中许多功能在 Manifest V2 和 Manifest V3 中均可使用。在转换时,您并不需要使用这些组件;但是,当它们取代旧功能时,您应优先使用这些功能而不是它们所取代的功能,并且预计被替换的功能最终会被弃用和移除。