清单文件格式

每个扩展程序的根目录中都必须有一个 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。
"background"
指定包含扩展程序的服务工件的 JavaScript 文件，该文件充当事件处理脚本。如需了解详情，请参阅扩展程序服务工作器简介。
"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"
定义扩展程序中可供网页或其他扩展程序访问的文件。如需了解详情，请参阅适用于网络的无障碍资源。

可选的 ChromeOS 按键

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