清单文件格式

每个扩展程序的根目录中都必须包含一个 manifest.json 文件，其中会列出有关该扩展程序的结构和行为的重要信息。本页将介绍扩展程序清单的结构及其可以包含的功能。

示例

以下示例清单展示了基本的清单结构和一些常用功能，您可以从这里开始创建自己的清单：

最小清单

{
  "manifest_version": 3,
  "name": "Minimal Manifest",
  "version": "1.0.0",
  "description": "A basic example extension with only required keys",
  "icons": {
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
}

注册内容脚本

{
  "manifest_version": 3,
  "name": "Run script automatically",
  "description": "Runs a script on www.example.com automatically when user installs the extension",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "content_scripts": [
    {
      "js": [
        "content-script.js"
      ],
      "matches": [
        "http://*.example.com//"
      ]
    }
  ]
}

注入内容脚本

{
  "manifest_version": 3,
  "name": "Click to run",
  "description": "Runs a script when the user clicks the action toolbar icon.",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "background": {
    "service_worker": "service-worker.js"
  },
  "action": {
    "default_icon": {
      "16": "images/icon-16.png",
      "32": "images/icon-32.png",
      "48": "images/icon-48.png",
      "128": "images/icon-128.png"
    }
  },
  "permissions": ["scripting", "activeTab"]
}

{
  "manifest_version": 3,
  "name": "Popup extension that requests permissions",
  "description": "Extension that includes a popup and requests host permissions and storage permissions .",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "action": {
    "default_popup": "popup.html"
  },
  "host_permissions": [
    "https://*.example.com/"
  ],
  "permissions": [
    "storage"
  ]
}

侧边栏

{
  "manifest_version": 3,
  "name": "Side panel extension",
  "version": "1.0",
  "description": "Extension with a default side panel.",
  "icons": {
    "16": "images/icon-16.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "side_panel": {
    "default_path": "sidepanel.html"
  },
  "permissions": ["sidePanel"]
}

清单键

以下是所有受支持的清单键的列表。

扩展平台所需的密钥

"manifest_version"
一个整数，用于指定扩展程序使用的清单文件格式版本。唯一支持的值是 3。
"name"
一个字符串，用于在 Chrome 应用商店、安装对话框和用户的 Chrome 扩展程序页面 (chrome://extensions) 中标识扩展程序。长度上限为 75 个字符。如需了解如何使用特定于语言区域的名称，请参阅国际化。
"version"
用于标识扩展程序版本号的字符串。如需了解如何设置版本号的格式，请参阅版本。

Chrome 应用商店所需的密钥

"description"
一个字符串，用于描述 Chrome 应用商店和用户扩展程序管理页面上的扩展程序。长度上限为 132 个字符。如需了解如何将说明本地化，请参阅国际化。
"icons"
代表扩展程序的一个或多个图标。如需了解最佳做法，请参阅图标。

可选键

"action"
定义扩展程序图标在 Google 工具栏中的外观和行为。如需了解详情，请参阅 chrome.action。
"author"
指定用于创建扩展程序的帐号的电子邮件地址。
"background"
指定包含扩展程序 Service Worker 的 JavaScript 文件，该 Service Worker 充当事件处理脚本。如需了解详情，请参阅扩展程序 Service Worker 简介。
"chrome_settings_overrides"
定义所选 Chrome 设置的替换项。如需了解详情，请参阅替换 Chrome 设置。
"chrome_url_overrides"
定义默认 Chrome 网页的替换值。如需了解详情，请参阅替换 Chrome 网页。
"commands"
定义扩展程序中的键盘快捷键。如需了解详情，请参阅 chrome.commands。
"content_scripts"
指定在用户打开某些网页时要使用的 JavaScript 或 CSS 文件。如需了解详情，请参阅内容脚本。
"content_security_policy"
定义对扩展程序可使用的脚本、样式和其他资源的限制。如需了解详情，请参阅内容安全政策。
"cross_origin_embedder_policy"
为 Cross-Origin-Embedder-Policy HTTP 标头指定值，该值用于配置在扩展程序页面中嵌入跨源资源。
"cross_origin_opener_policy"
指定 Cross-Origin-Opener-Policy HTTP 标头的值，可让您确保顶级扩展程序页面不会与跨源文档共享浏览上下文组。
"declarative_net_request"
定义 declarativeNetRequest API 的静态规则，以允许屏蔽和修改网络请求。
"default_locale"
一个字符串，用于定义支持多个语言区域的扩展程序的默认语言。例如“en”和“pt_BR”。此键在已本地化的扩展程序中是必需的，不得在未本地化的扩展程序中使用。如需了解详情，请参阅国际化。
"devtools_page"
定义使用 DevTools API 的页面。
"export"
允许从扩展程序导出资源。如需了解详情，请参阅导出。
"externally_connectable"
指定哪些其他网页和扩展程序可以连接到您的扩展程序。如需了解详情，请参阅 "externally_connectable"。
"homepage_url"
一个字符串，用于指定扩展程序首页的网址。如未定义，则主页默认为扩展程序的 Chrome 应用商店页面。如果您在自己的网站上托管扩展程序，此字段会特别有用。
"host_permissions"
列出允许您的扩展程序与之互动的网页，使用网址匹配模式定义。系统会在安装应用时请求这些网站的用户权限。如需了解详情，请参阅主机权限。
"import"
允许将资源导入扩展程序。如需了解详情，请参阅导入。
"incognito"
定义扩展程序在无痕模式下的行为方式。支持的值包括 "spanning"、"split" 和 "not_allowed"。如需了解详情，请参阅无痕模式。
"key"
指定用于各种开发用例的扩展程序 ID。如需了解详情，请参阅键。
"minimum_chrome_version"
定义可安装扩展程序的最低 Chrome 版本。该值必须是现有 Chrome 浏览器版本字符串的子字符串，例如 "107" 或 "107.0.5304.87"。如果用户的 Chrome 版本低于最低版本，则会在 Chrome 应用商店中看到“不兼容”警告，并且无法安装您的扩展程序。如果您将此扩展程序添加到现有扩展程序，则 Chrome 版本较低的用户不会收到您的扩展程序的自动更新。这包括处于临时模式的企业用户。
"oauth2"
允许使用 OAuth 2.0 安全 ID。此键的值必须是具有 "client_id" 和 "scopes" 属性的对象。如需了解详情，请参阅 OAuth 2.0 教程。
"omnibox"
允许此扩展程序在 Chrome 地址栏中注册关键字。如需了解详情，请参阅多功能框。
"optional_host_permissions"
为您的扩展程序声明可选的主机权限。
"optional_permissions"
为您的扩展程序声明可选权限。
"options_page"
指定 options.html 文件的路径，以使扩展程序用作选项页面。如需了解详情，请参阅为用户提供选项。
"options_ui"
指定 HTML 文件的路径，该文件允许用户从 Chrome 扩展程序页面更改扩展程序选项。如需了解详情，请参阅嵌入式选项。
"permissions"
允许使用特定的扩展程序 API。如需了解一般说明，请参阅权限。各个 API 的参考页面列出了它们所需的权限。
"requirements"
列出使用扩展程序所需的技术。如需查看受支持要求的列表，请参阅要求。
"sandbox"
定义一组无权访问扩展程序 API 或直接访问非沙盒化页面的扩展程序页面。如需了解详情，请参阅沙盒。
"short_name"
一个字符串，其中包含在字符空间有限时要使用的扩展名称的缩写版本。长度上限为 12 个字符。如果未指定，则会显示“name”键的截断版本。
"side_panel"
标识要在 sidePanel 中显示的 HTML 文件。
"storage"
为代管式存储区域声明 JSON 架构。如需了解详情，请参阅存储区域的清单。
"tts_engine"
将扩展程序注册为文字转语音引擎。如需了解详情，请参阅 ttsEngine API。
"update_url"
一个字符串，包含扩展程序的更新页面的网址。如果您在 Chrome 应用商店之外托管扩展程序，请使用此密钥。
"version_name"
一个描述扩展程序版本的字符串。例如 "1.0 beta" 和 "build rc2"。如果未指定，则“版本”值会显示在扩展程序管理页面上。
"web_accessible_resources"
定义扩展程序中可由网页或其他扩展程序访问的文件。如需了解详情，请参阅可通过 Web 访问的资源。

可选的 ChromeOS 密钥

"file_browser_handlers"
提供对 fileBrowserHandler API 的访问权限，该 API 可让扩展程序访问 ChromeOS 文件浏览器。
"file_handlers"
指定让 ChromeOS 扩展程序处理的文件类型。如需了解详情，请参阅 file_handlers。
"file_system_provider_capabilities"
允许访问 fileSystemProvider API，以便扩展程序创建 ChromeOS 可以使用的文件系统。
"input_components"
允许使用 Input Method Editor API。如需了解详情，请参阅 input_components。