web_accessible_resources

描述

有时，您会希望将资源（例如图片、HTML、CSS 或 JavaScript）打包到扩展程序中，并使其可供网页和其他扩展程序访问。

例如，Beastify 示例扩展会用用户选择的野兽图片替换网页。野兽图片随扩展程序打包。为了使选定的图片可见，扩展程序会添加 <img> 元素，其 src 属性指向野兽的图片。为了让网页能够加载这些图片，它们必须设为 Web 可访问。

使用 web_accessible_resources 键，您可以列出所有希望提供给网页的打包资源。您将它们指定为相对于 manifest.json 文件的路径。

请注意，内容脚本不需要列为 Web 可访问资源。

如果某个扩展程序希望使用 webRequest 或 declarativeNetRequest 将公共 URL（例如 HTTPS）重定向到打包在扩展程序中的页面，那么该扩展程序必须在 web_accessible_resources 键中列出该页面。

Manifest V2 语法

在 Manifest V2 中，Web 可访问资源会以数组的形式添加到键下，如下所示：

"web_accessible_resources": [
  "images/my-image.png"
]

Manifest V3 语法

在 Manifest V3 中，web_accessible_resources 键是一个对象数组，如下所示：

{
  // …
  "web_accessible_resources": [
    {
      "resources": ["test1.png", "test2.png"],
      "matches": ["https://web-accessible-resources-1.example.com/*"]
    },
    {
      "resources": ["test3.png", "test4.png"],
      "matches": ["https://web-accessible-resources-2.example.com/*"],
      "use_dynamic_url": true
    }
  ]
  // …
}

每个对象都必须包含一个 "resources" 属性，以及以下属性中的 "matches" 或 "extension_ids" 属性之一：

使用 web_accessible_resources

假设您的扩展程序包含一个图片文件，路径为 images/my-image.png，如下所示：

my-extension-files/
    manifest.json
    my-background-script.js
    images/
        my-image.png

要使网页能够使用 <img> 元素，其 src 属性指向此图片，您需要如下指定 web_accessible_resources：

"web_accessible_resources": ["images/my-image.png"]

然后，可以通过类似以下的 URL 访问该文件：

moz-extension://<extension-UUID>/images/my-image.png"

<extension-UUID> **不是**您的扩展程序的 ID。此 ID 是为每个浏览器实例随机生成的。这可以防止网站通过检查用户安装的扩展程序来对其进行指纹识别。

获取资源 URL 的推荐方法是使用 runtime.getURL，并传入相对于 manifest.json 的路径，例如：

browser.runtime.getURL("images/my-image.png");
// something like:
// moz-extension://944cfddf-7a95-3c47-bd9a-663b3ce8d699/images/my-image.png

此方法可以为您提供正确的 URL，而不管您的扩展程序运行在哪个浏览器上。

通配符

web_accessible_resources 条目可以包含通配符。例如，以下条目也可以包含 "images/my-image.png" 处的资源：

  "web_accessible_resources": ["images/*.png"]

安全

如果您使某个页面 Web 可访问，任何网站都可以链接或重定向到该页面。然后，该页面应将任何输入（例如 POST 数据）视为来自不受信任的来源，就像普通网页一样。

Web 可访问的扩展资源不会被 CORS 或 CSP 阻止。由于能够绕过安全检查，扩展程序应尽可能避免使用 Web 可访问的脚本。Web 可访问的扩展脚本可能会被恶意网站意外滥用，从而削弱其他网站的安全性。请遵循 安全最佳实践，避免在网页中注入 moz-extension:-URL，并确保第三方库是最新的。

示例

Manifest V2 示例

"web_accessible_resources": ["images/my-image.png"]

使 "images/my-image.png" 处的文件的 Web 可访问，以便任何网站和扩展程序都可以访问。

Manifest V3 示例

"web_accessible_resources": [
  {
    "resources": [ "images/my-image.png" ],
    "extension_ids": ["*"],
    "matches": [ "*://*/*" ]
  }
]

使 "images/my-image.png" 处的文件的 Web 可访问，以便任何网站和扩展程序都可以访问。

建议仅在需要时指定 extension_ids 或 matches。例如，如果资源只需要在 example.com 的网页上可访问：

"web_accessible_resources": [
  {
    "resources": [ "images/my-image.png" ],
    "matches": [ "https://example.com/*" ]
  }
]

扩展程序示例

• beastify
• dnr-redirect-url

浏览器兼容性