host_permissions

类型 数组
强制 否
清单版本 3 或更高
示例
json
"host_permissions": [
  "*://mdn.org.cn/*",
  "*://*.example.org/*"
]

使用 host_permissions 键来请求对扩展中读取或修改主机数据的 API 的访问权限，例如 cookies、webRequest 和 tabs。此键是一个字符串数组，每个字符串都是对权限的请求。

请求的权限和用户提示

用户可以 授予或撤销主机权限，这是按需进行的。因此，大多数浏览器将 host_permissions 视为可选。

安装时，当您使用此键请求权限时

  • 在 Firefox 126 之前，清单 V3 扩展的请求的主机权限不会显示在安装提示中。从 Firefox 127 开始，在 host_permissions 和 content_scripts 中列出的主机权限将显示在安装提示中。但是，如果扩展更新请求新的主机权限，则不会向用户显示这些权限。请参阅 (Firefox 错误 1893232).
  • Chrome 会在安装提示中显示权限。
  • Safari 不会在安装提示中显示请求的主机权限。

您的扩展可以在安装后立即使用 permissions.contains 检查它是否具有所有必需的权限。如果没有必要的权限，它可以使用 permissions.request 请求它们。在请求权限之前提供一个入门步骤来解释为什么要需要一些权限可能也很有帮助。

由于授予主机权限的请求可能会影响用户安装您的扩展的意愿，因此请求主机权限值得仔细考虑。例如，您要避免请求不必要的主机权限，并且可能希望在您的扩展的商店描述中提供有关您为什么请求主机权限的信息。文章 请求正确的权限 提供了有关您应该考虑的问题的更多信息。

有关如何测试和预览权限请求的信息，请参阅扩展工作坊网站上的 测试权限请求。

格式

主机权限指定为 匹配模式，每个模式都标识扩展请求额外特权的一组 URL。例如，主机权限可以是 "*://mdn.org.cn/*"。

额外特权包括

  • XMLHttpRequest 和 fetch 访问这些源，没有跨源限制（但内容脚本的请求除外，因为清单 V2 中的情况就是这样）。
  • 能够读取特定于标签页的元数据，而无需“标签页”权限，例如 tabs.Tab 对象的 url、title 和 favIconUrl 属性。
  • 能够使用 tabs.executeScript() 将脚本以编程方式注入从这些源提供的页面。
  • 能够从这些主机接收来自 webrequest API 的事件。
  • 能够使用 cookies API 访问该主机上的 Cookie，只要还包括 "cookies" API 权限。
  • 绕过跟踪保护，用于指定主机为完整域或带通配符的扩展页面。

在 Firefox 中，扩展会为其来源获得主机权限，其来源的格式为

url
moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/

其中 60a20a9b-1ad4-af49-9b6c-c64c98c37920 是扩展的内部 ID。扩展可以通过调用 extension.getURL() 以编程方式获取此 URL

js
browser.extension.getURL("");
// moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/

示例

json
 "host_permissions": ["*://mdn.org.cn/*"]

请求对 developer.mozilla.org 下的页面的特权访问。

示例扩展

浏览器兼容性

BCD 表格仅在浏览器中加载