Chrome 浏览器插件 V3 版本 Manifest.json 文件全字段解析
Manifest.json
文件格式每个扩展程序的根目录中都必须有一个
manifest.json
文件,其中列出了有关该扩展程序的结构和行为的重要信息。
Demo
展示{
"manifest_version": 3,
"name": "My Chrome Ext",
"version": "1.0.0",
"description": "Chrome Ext",
"icons": {
"48": "icon-48.png",
"128": "icon-128.png"
},
}
content_scripts
{
"manifest_version": 3,
"name": "Run script automatically",
"description": "Add Context Scripts",
"version": "1.0",
"icons": {
"16": "icon-16.png",
"32": "icon-32.png",
"48": "icon-48.png",
"128": "icon-128.png"
},
"content_scripts": [
{
"js": [
"content-script.js"
],
"matches": [
"http://*.example.com//"
]
}
]
}
service_worker
{
"manifest_version": 3,
"name": "Click to run",
"description": "Add Service Worker",
"version": "1.0",
"icons": {
"16": "icon-16.png",
"32": "icon-32.png",
"48": "icon-48.png",
"128": "icon-128.png"
},
"background": {
"service_worker": "service-worker.js"
},
"action": {
"default_icon": {
"16": "icon-16.png",
"32": "icon-32.png",
"48": "icon-48.png",
"128": "icon-128.png"
}
},
"permissions": ["scripting", "activeTab"]
}
action
{
"manifest_version": 3,
"name": "Popup extension that requests permissions",
"description": "Add Action",
"version": "1.0",
"icons": {
"16": "icon-16.png",
"32": "icon-32.png",
"48": "icon-48.png",
"128": "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.json
文件字段及解析Chrome
插件所必需的 key
manifest_version
name
Chrome
应用商店、安装对话框和用户的 Chrome
扩展程序页面 (chrome://extensions
) 中标识扩展程序。version
"manifest_version": 3,
"name": "My Chrome Ext Name",
"version": "0.0.1",
Chrome
应用商店所需的 key
description
JSON
字符串,用于描述 Chrome
网上应用店和用户的扩展程序管理页面上的扩展程序。icons
PNG
文件,但允许使用其他文件格式(SVG
和 WebP
文件除外)。Chrome
应用商店中分发扩展程序,则必须提供图标。
图标大小 | 图标的使用 |
---|---|
16x16 | 扩展程序页面和上下文菜单上的网站图标。 |
32x32 | Windows 计算机通常需要此大小。 |
48x48 | 显示在“扩展程序”页面上。 |
128x128 | 安装时会显示在 Chrome 应用商店中。 |
{
"manifest_version": 3,
"name": "chrome extension",
"version": "0.0.1",
"description": "My Chrome Extension description",
"icons": {
"16": "public/icons/icon_16.png",
"32": "public/icons/icon_32.png",
"48": "public/icons/icon_48.png",
"128": "public/icons/icon_128.png"
}
}
Chrome
插件可选 key
action
Google
工具栏中的外观和行为。action
键(及其子项)是可选的。如果未添加此扩展程序,相应扩展程序仍会显示在工具栏中,以便用户访问此扩展程序的菜单。因此,建议始终至少包含 action
和 default_icon
键。{
"name": "Action Extension",
"action": {
"default_icon": {
"16": "images/icon16.png",
"24": "images/icon24.png",
"32": "images/icon32.png"
},
"default_title": "Click Me",
"default_popup": "popup.html"
},
}
popup.html
是点击chrome
按钮弹出的页面
author
{
"author": {
"email": "[email protected]"
},
}
background
Service Worker
(充当事件处理程序)的 JavaScript
文件。 "background": {
"service_worker": "service-worker.js",
"type": "module"
}
chrome_settings_overrides
Chrome
设置的替换项。Chrome
设置的方式。该 API
适用于 Windows
和 Mac
的所有当前版本的 Chrome
。search_provider
、homepage
和 startup_pages
属性的所有值都可以使用 chrome.i18nAPI
进行本地化。search_provider
、homepage
和 startup_pages
网址值进行参数化。alternate_urls
(字符串数组,可选)
search_url.
之外,还可使用的网址格式列表encoding
(字符串,可选)
prepopulated_id
,则必须执行此操作。favicon_url
(字符串,可选)
prepopulated_id
,则必须执行此操作。homepage
(字符串,可选)
image_url
(字符串,可选)
image_url_post_params
(字符串,可选)
image_url
的 post
参数。is_default
(布尔值,必需)
keyword
(字符串,可选)
prepopulated_id
,则必须执行此操作。name
(字符串,可选)
prepopulated_id
,则必须执行此操作。prepopulated_id
(整数,可选)
Chrome
内置搜索引擎的 ID
。search_provider
(对象,可选)
search_url
(字符串,必需)
search_url_post_params
(字符串,可选)
search_url
的 post
参数。startup_pages
(字符串数组,可选)
suggest_url
(字符串,可选)
suggest_url_post_params
(字符串,可选)
suggest_url
的 post
参数。{
"name": "My extension",
"chrome_settings_overrides": {
"homepage": "https://www.homepage.com",
"search_provider": {
"name": "name.__MSG_url_domain__",
"keyword": "keyword.__MSG_url_domain__",
"search_url": "https://www.foo.__MSG_url_domain__/s?q={searchTerms}",
"favicon_url": "https://www.foo.__MSG_url_domain__/favicon.ico",
"suggest_url": "https://www.foo.__MSG_url_domain__/suggest?q={searchTerms}",
"instant_url": "https://www.foo.__MSG_url_domain__/instant?q={searchTerms}",
"image_url": "https://www.foo.__MSG_url_domain__/image?q={searchTerms}",
"search_url_post_params": "search_lang=__MSG_url_domain__",
"suggest_url_post_params": "suggest_lang=__MSG_url_domain__",
"instant_url_post_params": "instant_lang=__MSG_url_domain__",
"image_url_post_params": "image_lang=__MSG_url_domain__",
"alternate_urls": [
"https://www.moo.__MSG_url_domain__/s?q={searchTerms}",
"https://www.noo.__MSG_url_domain__/s?q={searchTerms}"
],
"encoding": "UTF-8",
"is_default": true
},
"startup_pages": ["https://www.startup.com"]
},
"default_locale": "de",
}
chrome_url_overrides
Chrome
网页的替换项。HTML
覆盖网页来替换 Google Chrome
通常提供的网页。扩展程序可以覆盖以下任意网页,但每个扩展程序只能覆盖 1 个网页:
Chrome
菜单中选择“书签管理器”菜单项(或者在 Mac 上)从“书签”菜单中选择“书签管理器”菜单项时显示的网页。也可以通过输入网址 chrome://bookmarks
来访问此页面。Chrome
菜单中选择“历史记录”菜单项(或在 Mac 上从“历史记录”菜单中选择“显示全部历史记录”)时显示的页面。也可以通过输入网址 chrome://history
来访问此页面。chrome://newtab
来访问此页面。{
"manifest_version": 3,
"name": "My extension",
"chrome_url_overrides" : {
"PAGE_TO_OVERRIDE": "myPage.html"
},
}
PAGE_TO_OVERRIDE
替换为以下项之一:
bookmarks
history
newtab
commands
commands API
可用于添加可触发扩展程序中操作的键盘快捷键,例如,打开浏览器操作或向扩展程序发送命令的操作。manifest.json
声明 commands
,才能使用此 API
。"commands": {
"run-foo": {
"suggested_key": {
"default": "Ctrl+Shift+Y",
"mac": "Command+Shift+Y"
},
"description": "Run "foo" on the current page."
}
}
content_scripts
JavaScript
或 CSS
文件。{
"name": "My extension",
"content_scripts": [
{
"matches": ["https://*.nytimes.com/*"],
"css": ["my-styles.css"],
"js": ["content-script.js"]
}
]
}
content_security_policy
如果没有在 manifest.json
中定义 content_security_policy
,将使用默认属性,默认值为:
{
"content_security_policy": {
"extension_pages": "script-src 'self'; object-src 'self';",
"sandbox": "sandbox allow-scripts allow-forms allow-popups allow-modals; script-src 'self' 'unsafe-inline' 'unsafe-eval'; child-src 'self';"
}
}
在这种情况下,扩展程序只会从自己的打包资源加载本地脚本和对象。WebAssembly
将停用,该扩展程序将不会运行内嵌 JavaScript
,也无法将字符串评估为可执行代码。如果添加了沙盒页面,页面将拥有更宽松的权限,可以从扩展程序外部评估脚本。
Chrome
对扩展程序页面强制执行最低的内容安全政策。这相当于在 manifest.json
中指定以下策略:
{
"content_security_policy": {
"extension_pages": "script-src 'self' 'wasm-unsafe-eval'; object-src 'self';"
}
}
extension_pages
策略的放宽限制不能超过此最小值。
cross_origin_embedder_policy
Cross-Origin-Embedder-Policy HTTP
标头的值,该标头用于配置在扩展程序页面中嵌入跨源资源。require-corp
credentialless
unsafe-none
{
"cross_origin_embedder_policy": {
"value": "require-corp"
},
}
cross_origin_opener_policy
Cross-Origin-Opener-Policy HTTP
标头的值,可让确保顶级扩展程序页面不会与跨源文档共享浏览上下文组。same-origin
same-origin-allow-popups
restrict-properties
unsafe-none
{
"cross_origin_opener_policy": {
"value": "same-origin"
},
}
declarative_net_request
declarativeNetRequest API
的静态规则,以允许拦截和修改网络请求。{
"name": "My extension",
"declarative_net_request" : {
"rule_resources" : [{
"id": "ruleset_1",
"enabled": true,
"path": "rules_1.json"
}, {
"id": "ruleset_2",
"enabled": false,
"path": "rules_2.json"
}]
},
"permissions": [
"declarativeNetRequest",
"declarativeNetRequestFeedback",
],
"host_permissions": [
"http://www.blogger.com/*",
"http://*.google.com/*"
],
}
default_locale
en
和 pt_BR
_locales
目录,则 Manifest.json
必须定义 default_locale
。devtools_page
DevTools API
的页面。devtools.panels API
创建面板并与之交互,包括将其他扩展程序页面作为面板或边栏添加到开发者工具窗口中。devtools.inspectedWindow API
获取已检查窗口的相关信息,并评估所检查窗口中的代码。devtools.network API
获取有关网络请求的信息。devtools.recorder API
扩展 Recorder
面板。{
"name": "Chrome Ext",
"version": "1.0",
"devtools_page": "devtools.html",
}
export
{
"version": "1.0",
"name": "My Shared Module",
"export": {
// Optional list of extension IDs explicitly allowed to
// import this Shared Module's resources. If no allowlist
// is given, all extensions are allowed to import it.
"allowlist": [
"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
]
}
// Note: no permissions are allowed in Shared Modules
}
externally_connectable
runtime.connect
和 runtime.sendMessage
连接到扩展程序。externally_connectable
键,则所有扩展程序都可以连接,但任何网页都无法连接。externally_connectable
时,如果未指定 ids: ["*"]
,其他扩展程序将无法连接到扩展程序。ids
ID
。如果留空或未指定,则任何扩展程序或应用都无法连接。通配符 *
将允许所有扩展程序和应用连接。matches
✅ 有效网址 | ❌ 网址无效 |
---|---|
*://example.com/ |
*://example.com/one/ |
http://*.example.org/* |
|
https://example.com/* |
http://*/* |
accepts_tls_channel_id
TLS
通道 ID
。{
"name": "My externally connectable extension",
"externally_connectable": {
"ids": [
"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
],
// If this field is not specified, no web pages can connect.
"matches": [
"https://*.google.com/*",
"*://*.chromium.org/*",
],
"accepts_tls_channel_id": false
},
}
homepage_url
Chrome
应用商店页面。如果在自己的网站上托管扩展程序,此字段特别有用。{
"manifest_version": 3,
"name": "chrome extension",
"version": "0.1.0",
"description": "My Chrome Extension",
"homepage_url": "https://guoqiankun.blog.csdn.net/",
}
host_permissions
permissions
optional_permissions
content_scripts.matches
host_permissions
optional_host_permissions
{
"name": "Permissions Extension",
"permissions": [
"activeTab",
"contextMenus",
"storage"
],
"optional_permissions": [
"topSites",
],
"host_permissions": [
"https://www.developer.chrome.com/*"
],
"optional_host_permissions":[
"https://*/*",
"http://*/*"
],
"manifest_version": 3
}
import
{
"version": "1.0",
"name": "My Importing Extension",
"import": [
{"id": "cccccccccccccccccccccccccccccccc"},
{"id": "dddddddddddddddddddddddddddddddd"
"minimum_version": "0.5" // optional
},
]
}
incognito
spanning
、split
和 not_allowed
。{
"incognito": "not_allowed"
}
key
ID
。
Chrome
扩展程序来源的请求。web_accessible_resources
。{
"manifest_version": 3,
"key": "ThisKeyIsChromeKey",
}
minimum_chrome_version
Chrome
版本。Chrome
浏览器版本字符串的子字符串,例如 “107” 或 “107.0.5304.87”。Chrome
版本低于最低版本,则会在 Chrome
应用商店中看到“不兼容”警告,并且无法安装扩展程序。如果将此扩展程序添加到现有扩展程序,则所用 Chrome
版本较低的用户将不会收到扩展程序的自动更新。{
"minimum_chrome_version": "120.0.6099.129"
}
oauth2
OAuth
2.0 安全 ID
。{
"name": "OAuth Tutorial FriendBlock",
...
"oauth2": {
"client_id": "yourExtensionOAuthClientIDWillGoHere.apps.googleusercontent.com",
"scopes":[""]
},
}
omnibox
Chrome
的地址栏中注册关键字。{
"omnibox": { "keyword": "newTab" },
}
optional_host_permissions
{
"optional_host_permissions":[
"https://*/*",
"http://*/*"
],
}
optional_permissions
{
"optional_permissions": [
"topSites",
],
}
options_page
{
"options_page": "index.html",
}
options_ui
HTML
文件的路径,该文件允许用户在 Chrome
扩展程序页面更改扩展程序选项。{
"name": "My extension",
"options_ui": {
"page": "options.html",
"open_in_tab": false
},
}
permissions
API
。"permissions": [
"storage",
"activeTab",
"scripting"
]
requirements
"requirements": {
"3D": {
"features": ["webgl"]
}
}
sandbox
API
或直接访问非沙盒化页面。content_security_policy
键中指定。API
,也无法直接访问未经过沙盒化的页面(可通过 postMessage()
与它们进行通信)。CSP
)(有自己的单独的 CSP
值)的约束。这意味着,例如,它可以使用内嵌脚本和 eval
。{
"content_security_policy": {
"sandbox": "sandbox allow-scripts; script-src 'self' https://example.com"
},
"sandbox": {
"pages": [
"page1.html",
"directory/page2.html"
]
},
}
short_name
name
键的截断版本。{
"short_name": "short name"
}
side_panel
sidePanel
中显示的 HTML
文件。{
"name": "My side panel extension",
"side_panel": {
"default_path": "sidepanel.html"
}
}
storage
JSON
架构。{
"name": "My enterprise extension",
"storage": {
"managed_schema": "schema.json"
},
}
tts_engine
{
"name": "My TTS Engine",
"version": "1.0",
"permissions": ["ttsEngine"],
"tts_engine": {
"voices": [
{
"voice_name": "Alice",
"lang": "en-US",
"event_types": ["start", "marker", "end"]
},
{
"voice_name": "Pat",
"lang": "en-US",
"event_types": ["end"]
}
]
},
"background": {
"page": "background.html",
"persistent": false
}
}
update_url
Chrome
应用商店之外托管扩展程序,需要添加此字段。{
"name": "My extension",
"update_url": "https://myhost.com/mytestextension/updates.xml",
}
version_name
1.0 beta
和 build rc2
。version
值。{
"version_name": "1.0 beta"
}
web_accessible_resources
{
"web_accessible_resources": [
{
"resources": [ "test1.png", "test2.png" ],
"matches": [ "https://web-accessible-resources-1.glitch.me/*" ]
}, {
"resources": [ "test3.png", "test4.png" ],
"matches": [ "https://web-accessible-resources-2.glitch.me/*" ],
"use_dynamic_url": true
}
],
}
ChromeOS
可选的 Key
file_browser_handlers
fileBrowserHandler API
的访问权限,该 API
允许扩展程序访问 ChromeOS
文件浏览器。{
"name": "My extension",
"file_browser_handlers": [
{
"id": "upload",
"default_title": "Save to Gallery", // What the button will display
"file_filters": [
"filesystem:*.jpg", // To match all files, use "filesystem:*.*"
"filesystem:*.jpeg",
"filesystem:*.png"
]
}
],
"permissions" : [
"fileBrowserHandler"
],
}
file_handlers
ChromeOS
扩展程序要处理的文件类型。"file_handlers": [
{
"action": "/open_text.html",
"name": "Plain text",
"accept": {
"text/plain": [".txt"]
}
"launch_type": "single-client"
}
]
file_system_provider_capabilities
fileSystemProvider API
,以便扩展程序创建 ChromeOS
可以使用的文件系统。{
"name": "My extension",
"permissions": [
"fileSystemProvider"
],
"file_system_provider_capabilities": {
"configurable": true,
"watchable": false,
"multiple_mounts": true,
"source": "network"
},
}
input_components
Input Method Editor API
。{
"input_components": [{
"name": "ToUpperIME",
"id": "ToUpperIME",
"language": "en",
"layouts": ["us::eng"]
}]
}