#Chrome扩展程序开发教程--03：Manifest

引言

        本系列博客旨在带来最新的Chrome扩展程序开发入门教程。

1、基本介绍

        所有的扩展程序必须在根目录中包含且只包含一个 manifest.json 文件。这个文件我们通常称为清单文件，里面记录了关于这个扩展程序的所有元数据：使用的文件，需要的权限，谁来处理事件，谁来处理网页等。
        本章中笔者对 manifest.json 中所有属性进行了总结，并按照重要性划分成了四部分。

2、必须属性

        这三个是必须指定的，含义就不解释了。

{"manifest_version": 3,"name": "My Extension","version": "1.0.1"
}

3、重要属性

3.1、permissions、host_permissions、optional_permissions、optional_host_permissions

        这些属性与权限相关，具体请见第四章。

3.2、background

        用于指定 service worker 文件，具体请见第五章。

3.3、content_scripts

        用于指定 content scripts 文件，具体请见第六章。

3.4、action

        通过指定 action 字段来控制扩展程序在 Chrome 中如何展现工具栏，如下所示：

{"name": "Action Extension",..."action": {"default_icon": {              // optional"16": "icons/16.png",   // optional"32": "icons/32.png",   // optional"48": "icons/48.png"    // optional},"default_title": "Click Me",   // optional, shown in tooltip"default_popup": "popup.html"  // optional},...
}

        default_icon 属性用于指定扩展程序的工具栏图标，该属性是一个字典，键为图像尺寸，值为图像路径。Chrome会根据用户电脑的屏幕分辨率来自动选择最合适的图标进行展示。当然，也可以通过 Chrome API 来动态设置工具栏图标，如下所示：

const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00';  // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });

        default_title 属性用于指定扩展程序的工具栏提示（Tooltip），当然也可以通过 action.setTitle() 来动态设置。
        default_popup 属性用于指定当用户点击扩展程序的工具栏后应当展现的内容。需要注意的是，popup 的内容大小必须位于 25x25 至 800x600 之间。当然也可以通过 action.setPopup() 来动态设置。

3.5、options_page

        用于指定 options 页面文件。扩展程序可以使用 options_page 来提供更多，更详细的交互功能，例如配置扩展程序可以在哪些网站上运行。如下所示：

{"name": "My extension",..."options_page": "options.html",...
}

3.6、options_ui

        与 options_page 不同的是，options_ui 是弹出一个小窗口来展示 options 页面，如下所示：

{"name": "My extension",..."options_ui": {"page": "options.html","open_in_tab": false},...
}

3.7、icons

        指定扩展程序需要用到的图标资源，推荐使用 png 格式图片。如下所示：

{..."icons": {"16": "icon16.png","32": "icon32.png","48": "icon48.png","128": "icon128.png"}...
}

3.8、commands

        用于指定扩展程序的一些快捷键，如下所示：

{"name": "My extension",..."commands": {"run-foo": {"suggested_key": {"default": "Ctrl+Shift+Y","mac": "Command+Shift+Y"},"description": "Run \\"foo\\" on the current page."},"_execute_action": {"suggested_key": {"windows": "Ctrl+Shift+Y","mac": "Command+Shift+Y","chromeos": "Ctrl+Shift+U","linux": "Ctrl+Shift+J"}}},...
}

3.9、event_rules

        用于定义事件规则，以指定何时应该调用扩展程序的特定部分。如下所示：

{"name": "Sample extension","event_rules": [{"event": "declarativeContent.onPageChanged","actions": [{"type": "declarativeContent.ShowPageAction"}],"conditions": [{"type": "declarativeContent.PageStateMatcher","css": ["video"]}]}],...
}

3.10、automation

        通过配置该属性并指定 host_permissions 或 activeTab 后，就可以让扩展程序使用 chrome.automation API。如下所示：

{..."automation": {"desktop": true,"interact": true,"matches": ["www.google.com" ]}...
}

        desktop 属性用于申请调用 getDesktop() 及其相关操作权限。
        interact 属性表示扩展程序是否可以使用与用户的交互操作相关的 Chrome API，如鼠标点击、键盘输入等。
        matches 属性用于指定 automation 能够访问的网页。

3.11、declarative_net_request

        用于建立一种新的网络请求方式。该属性允许扩展程序使用声明式规则来修改网络请求的行为，例如拦截、重定向、修改参数等，而无需使用传统的网络请求钩子（如 XMLHttpRequest ）。
        声明式网络请求可以帮助扩展程序更高效地修改网络请求，同时减少资源消耗和延迟。此外，它还提供了更加安全的网络请求方式，因为它可以帮助避免以前可能引起跨站点脚本攻击的常见漏洞。内容较多，这里不展开介绍，有兴趣的读者可以自行查阅 chrome.declarativeNetRequest。

3.12、minimum_chrome_version

        用于指定扩展程序能安装的最小 Chrome 版本。如下所示：

{..."minimum_chrome_version": "107"...
}

3.13、requirements

        用于指定扩展程序所依赖的浏览器功能、API 和其他扩展，如：所需的最低 Chrome 版本、所需的权限（如访问网页内容、管理标签页等）、所需的 API（如 storage 、notifications 等）以及所需的其他扩展程序。通过使用 requirements 属性，开发者可以确保扩展程序在运行时能够访问必要的资源和功能，并避免不必要的错误和崩溃。如下所示：

"requirements": {"3D": {"features": ["webgl"]}"plugins": {"npapi": true}
}

3.14、update_url

        如果扩展程序不在 Chrome 商店中，则必须包含该属性，如下所示：

{"name": "My extension",..."update_url": "https://myhost.com/mytestextension/updates.xml",...
}

        返回的 updates.xml 格式如下所示：

<?xml version='1.0' encoding='UTF-8'?>
<gupdate xmlns='http://www.google.com/update2/response' protocol='2.0'><app appid='aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'><updatecheck codebase='https://myhost.com/mytestextension/mte_v2.crx' version='2.0' /></app>
</gupdate>

        appid 属性表示扩展程序的 ID。
        codebase 属性指向 crx 扩展程序文件。
        version 属性表示扩展程序版本。

3.15、web_accessible_resources

        用来指定可从扩展程序中访问的资源，包括 HTML、图片、CSS、JavaScript 等文件。这些资源可以在页面中使用 chrome.extension.getURL() 方法进行访问。这种方式可以帮助开发者提高扩展程序的安全性，因为通过 web_accessible_resources 指定的资源只有在指定的 URL 下才能被访问，而不会被其他网站访问。同时也可以让开发者更方便地调用和管理扩展程序中的资源。如下所示：

{..."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}],...
}

4、安全属性

4.1、input_components

        用于自定义输入组件的 API，它可以让开发者自定义输入控件的样式和功能，使用户在填写表单时有更好的体验。该属性可以被用于 text、number、email 等类型的输入框，可以自定义输入框的外观、自动完成列表、输入验证和键盘快捷键等。此外， input_components 还能够帮助开发者提高扩展程序的安全性，因为它可以防止用户在输入敏感信息时被键盘记录器或恶意软件截取和窃取。

4.2、incognito

        用于指定扩展程序在 Chrome 的隐身模式下的行为，取值有：
        spanning：表示扩展程序将会在隐身模式和正常模式下共享相同的状态和数据。
        split：表示扩展程序将在隐身模式下使用单独的状态和数据，与正常模式下的状态和数据分离。
        not_allowed：表示扩展程序将完全被禁止在隐身模式下运行。

4.3、sandbox

        该属性是一个安全机制，用于隔离扩展程序的 JavaScript 代码与浏览器环境之间的交互，以确保扩展不会在运行时访问到敏感的浏览器资源。当 sandbox 属性设置为 true 时，扩展程序将会在单独的沙箱中运行，这意味着其 JavaScript 代码只能在该沙箱内部访问受控资源，而不能跨越沙箱之外的浏览器环境访问其他资源，例如浏览器的 cookies、本地存储等。这样，即使扩展被恶意攻击，也不会对浏览器和用户造成安全问题。

4.4、oauth2

        用于进行 OAuth2 授权流程的配置参数，用于从第三方服务或 API 中获取授权访问权限。这些属性包括客户端 ID、客户端密钥、回调 URL 等，扩展程序可以根据这些属性从外部服务中获取访问令牌，然后使用访问令牌进行 API 调用。OAuth2 授权与认证流程非常安全，因为它不需要用户提供其用户名和密码，而是使用一次性令牌来完成授权和访问。

4.5、content_security_policy

        用于规定扩展程序中加载的资源允许的来源和类型。它可以限制扩展程序中包含的 HTML、JavaScript、CSS 等代码通过 HTTP、HTTPS、插件等方式访问外部资源，可以防止恶意脚本在扩展程序中执行不受信任代码，从而增强扩展程序的安全性。如下所示：

{..."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';"}...
}

4.6、cross_origin_embedder_policy

        用于设置跨域嵌入策略。它可以在 Chrome 中实现更强的安全性，并帮助防止网站被攻击。该属性允许插件将策略设置为 strict-origin-when-cross-origin 。这个策略允许插件通过 iframe 向另一个源请求资源，但当请求源和 iframe 源不同时，只允许出现相同源的请求。这大大减少了跨站点攻击的风险，并防止不安全的资源访问。如下所示：

{..."cross_origin_embedder_policy": {"value": "require-corp"},...
}

4.7、cross_origin_opener_policy

        用于设置跨源 iframe 与打开它的窗口之间的安全策略。该属性控制在一个源下打开的文档是否允许访问打开它的窗口。其值可以为 “same-origin”、“same-origin-allow-popups”、“unsafe-none” 和 null 。默认情况下，该属性值为 null ，表示没有限制。
        当该属性值为 “same-origin” 时，文档只能访问与其同源的窗口。当值为 “same-origin-allow-popups” 时，文档可以访问与其同源的窗口，但允许来自外部源而被允许通过 window.opener 访问到当前源的窗口。当该值为 “unsafe-none” 时，所有窗口间均可以直接互相访问，这将降低安全性。
        通过设置 cross_origin_opener_policy 属性，开发者可以有效地控制在扩展程序的不同文档间进行安全的跨源通信。如下所示：

{..."cross_origin_opener_policy": {"value": "same-origin"},...
}

4.8、externally_connectable

        用于列出哪些网站或扩展程序可以通过 Chrome 的 runtime.connect()、runtime.sendMessage()、tabs.sendMessage() 或者其他类似的 API 与当前扩展程序通信。这个属性用于确保只有指定的网站或者扩展程序可以与扩展程序交互通信，从而增加了通信的安全性。

5、其它属性

5.1、default_locale

        本地化属性，指定扩展程序的语言。

5.2、description

        指定扩展程序的功能简介。

5.3、author

        指定扩展程序的作者信息。

5.4、version_name

        版本名称

5.5、short_name

        扩展程序的简称。

5.6、omnibox

        用于自定义浏览器地址栏的行为。通过 omnibox 属性，开发者可以向浏览器地址栏添加自定义的关键字、快捷键以及处理用户在地址栏输入的指令，从而实现一些快速搜索、跳转到指定页面等功能。如下所示：

{"name": "Aaron's omnibox extension","version": "1.0","omnibox": { "keyword" : "aaron" },"icons": {"16": "16-full-color.png"},"background": {"persistent": false,"scripts": ["background.js"]}
}

5.7、devtools_page

        用于自定义 DevTools 界面，也就是我们按 F12 出现的那个界面，内容较多，这里不展开介绍，有兴趣的读者可以自行查阅 Extending DevTools。

5.8、homepage_url

        用于设置扩展程序的主页，如下所示：

{..."homepage_url": "https://example.com,",...
}

5.9、chrome_url_overrides

        用于覆盖 Chrome 中的内置页面，如：chrome://bookmarks、chrome://history 和 chrome://newtab，但需要注意的是，一个扩展程序只能覆盖其中的一个页面，如下所示：

{"name": "My extension",..."chrome_url_overrides" : {"PAGE_TO_OVERRIDE": "myPage.html"},...
}

5.10、chrome_settings_overrides

        用于覆盖 Chrome 本身的一些配置属性，如下所示：

{"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",...
}

5.11、tts_engine

        用于指定扩展程序使用的语音引擎。它指定了将要使用的语音引擎的名称或 ID，并允许开发人员将不同的语音引擎与其扩展程序结合使用。通过设置 tts_engine 属性，开发人员可以根据自己的需求选择最适合他们扩展程序的语音引擎。

5.12、export

        用于导出模块的，它可以将一个模块或者一个变量、函数等暴露给其他模块或应用程序使用。

5.13、import

        用于指定扩展程序中的 JavaScript 模块或其他资源的来源，使扩展程序能够在其不同的组件之间共享代码和资源。

5.14、storage

        用于在浏览器中存储和读取数据。它类似于浏览器中的 localStorage 和 sessionStorage，但它允许扩展程序通过特定的键和值来访问和修改存储的数据。使用storage属性，扩展程序可以存储用户偏好、设置和其他数据，以便在不同的会话之间保持状态和同步数据。此外，storage属性还允许扩展程序共享数据和设置，以便在使用多个浏览器时保持一致性。如下所示：

{"name": "My enterprise extension","storage": {"managed_schema": "schema.json"},...
}

5.15、file_browser_handlers

        用于指定可用于打开某些文件类型的程序或应用程序。 通过该属性，开发人员可以向 Chrome 浏览器添加自定义文件处理程序。当用户尝试打开某个文件类型时，可以在文件打开对话框中选择安装了该处理程序的应用程序。

5.16、file_system_provider_capabilities

        用于指定 Chrome 扩展程序提供的文件系统的功能和支持的文件操作类型。