谷歌插件开发：manifest.json 配置文件详解

在当今的互联网时代，浏览器插件扮演着重要的角色，为用户提供了各种定制化的功能和增强体验。Google Chrome作为最受欢迎的浏览器之一，也提供了丰富的插件生态系统。而在Chrome插件的开发中，manifest.json配置文件起着至关重要的作用。本节将详细讲解manifest.json文件的作用、重要性以及其结构，帮助您理解插件开发过程中的关键概念和操作，并提供实用方法供您深入学习和执行。

---

基本介绍

manifest.json文件在Chrome插件开发中起着关键的作用。它不仅提供了插件的基本信息，还定义了插件的行为、权限和资源等。下面是manifest.json文件的几个重要作用：

• 描述插件信息：manifest.json文件中包含了插件的名称、版本、作者等基本信息，帮助用户和开发者快速了解插件的特性和来源。
• 定义插件行为：通过manifest.json文件，开发者可以定义插件的行为，例如添加浏览器工具栏按钮、注入脚本到网页中、拦截请求等。
• 管理权限：manifest.json文件中的"permissions"字段用于声明插件需要访问的特定权限，以确保用户数据和隐私的安全。
• 引入资源：manifest.json文件还可以引入插件所需的资源文件，例如图标、样式表、脚本文件等。

manifest.json文件的结构由多个字段组成，每个字段都具有特定的含义和作用。下面是一个典型的结构示例：

{
  "manifest_version": 2,
  "name": "My Extension",
  "version": "1.0",
  "description": "This is a sample extension",
  "permissions": [
    "tabs",
    "storage"
  ],
  "background": {
    "scripts": [
      "background.js"
    ],
    "persistent": false
  },
  "browser_action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "images/icon16.png",
      "48": "images/icon48.png",
      "128": "images/icon128.png"
    }
  },
  "icons": {
    "16": "images/icon16.png",
    "48": "images/icon48.png",
    "128": "images/icon128.png"
  },
  "content_scripts": [
    {
      "matches": [
        "https://example.com/*"
      ],
      "js": [
        "content.js"
      ],
      "css": [
        "styles.css"
      ]
    }
  ]
}

这个文件包含了插件的基本信息，包括插件的名称、版本号和描述等。那么我们填写的描述信息到底有什么作用呢？

作用

我们来看一下 manifest.json 的作用。首先，它告诉 Chrome 浏览器如何加载和运行插件。当您加载一个插件时，Chrome 会查找 manifest.json 文件并根据其中的信息确定插件的名称、版本号、描述等基本信息。然后，Chrome 会检查权限列表并确定插件是否有足够的权限来执行所需的任务。最后，Chrome 根据指示加载所需的脚本文件和图标，并将其添加到浏览器中。

---

可配置字段

以下是 manifest.json 中所有可配置字段的详细注释：

{
  "name": "My Extension", // 插件名称，字符串类型
  "version": "1.0.0",  // 插件版本号，字符串类型
  "description": "This is my first extension.", // 插件描述，字符串类型
  "icons": {
    "16": "icon16.png",  // 16x16 像素的图标文件路径
    "32": "icon32.png",  // 32x32 像素的图标文件路径
    "48": "icon48.png",  // 48x48 像素的图标文件路径
    "128": "icon128.png" // 128x128 像素的图标文件路径
  },
  "browser_action": {   // 浏览器动作，该字段用于定义当用户单击浏览器操作按钮时执行的操作
    "default_icon": "icon.png", // 默认图标的文件路径
    "default_title": "My Extension", // 鼠标指针悬停在浏览器操作按钮上显示的默认标题
    "default_popup": "popup.html" // 弹出窗口的 HTML 文件路径
  },
  "content_scripts": [ // 内容脚本，该字段定义了将应用于哪些网站，以及应用程序如何与网站交互
    {
      "matches": ["<all_urls>"], // 匹配的 URL，字符串数组。使用“*”通配符匹配所有 URL。
      "js": ["content.js"], // 要注入网页中的 JavaScript 文件列表
      "css": ["style.css"], // 要注入网页中的 CSS 文件列表
      "run_at": "document_idle" // 脚本何时运行。可选值有：document_start、document_end 和 document_idle。
    }
  ],
  "permissions": [ // 权限，该字段定义了插件需要访问的资源和功能，例如浏览器标签、存储、网络等等。
    "tabs", // 访问当前活动标签页
    "storage", // 访问扩展的本地存储
    "http://*/*" // 允许插件访问所有 http 协议的网站
  ],
  "background": { // 后台脚本，该字段在后台长时间运行的脚本，也称为持久化背景页
    "scripts": ["background.js"], // 后台脚本文件列表
    "persistent": false // 是否保持持久化，如果设置为 false，当插件不再需要后台页面时，将自动卸载后台页面
  },
  "options_page": "options.html", // 插件选项页面的 HTML 文件路径
  "manifest_version": 2 // manifest.json 文件版本号。必须设置为2。
}

下面我们根据以上的一些重要字段进行剖析讲解，让您更了解我们以后在实现任务需求时应该怎么去配置

---

1. browser_action - （可选）定义插件在浏览器工具栏中的操作按钮

browser_action 是 manifest.json 文件中的一个可选字段，它用于定义插件在浏览器工具栏中的操作按钮。当用户单击该按钮时，插件可以打开一个弹出窗口来执行某些操作，例如显示插件的设置页面，执行搜索操作，显示通知等等。它主要包含两个子字段：default_icon和default_popup，其中：

• default_icon用于指定浏览器操作图标的路径和尺寸，可以是单个图标或多个图标组成的对象。
• default_popup用于指定浏览器操作图标点击后弹出的页面，应该是一个相对于插件根目录的HTML文件路径。

需要注意的事项 ⚠️

1. 图标尺寸：在设置图标时，请务必遵循 Chrome 的建议尺寸（16x16、19x19、32x32、38x38、48x48 和 128x128），以确保图标在各种设备和分辨率下都能正常显示。如果您的图标不符合要求，Chrome 可能会自动缩放它，在某些情况下可能导致质量损失或变形。
2. 弹出窗口大小：在创建 popup 页面时，请考虑到弹出窗口大小的限制。通常情况下，建议将弹出窗口的大小限制在 600x800 像素以内，以确保可以适应大多数屏幕分辨率和比例。
3. 脚本加载顺序：如果您的插件同时使用了 browser_action 和 content_scripts，您需要确保它们的加载顺序正确。通常情况下，content_scripts 应该在后台页面之前加载，而 browser_action 应该在用户单击操作按钮之后才加载。

2. content_scripts - （可选）定义插件在网页中注入的 JavaScript 或 CSS 代码

content_scripts 是 manifest.json 文件中的一个可选字段，它用于定义插件在网页中注入的 JavaScript 或 CSS 代码。主要用于扩展插件的能力，让插件能够与网页进行交互并改变其行为。在加载网页时，content_scripts 中定义的代码会被注入到页面中，并在页面加载完成后运行。通过这种方式，您可以访问和修改页面元素、处理事件、发送请求等等。

使用 content_scripts，您可以实现许多有用的功能，例如：

1. 自动填充表单：可以轻松地自动填充表单，并向用户提供快速登录和注册等功能。
2. 修改页面样式：想添加某些自定义样式或主题，可以添加自定义 CSS，以改变页面的外观和布局。
3. 捕获网页事件：可以监听和捕获网页事件，例如鼠标点击、键盘输入和页面滚动等等。
4. 添加新的 UI 元素：可以添加新的 UI 元素，例如按钮、菜单和弹出窗口，以实现各种功能。

现在，我们来看一下如何在 manifest.json 文件中使用 content_scripts 字段。以下是一个最简单的示例：

{
  "name": "My Extension",
  "version": "1.0",
  "description": "This is my first extension.",
  "content_scripts": [
    {
      "matches": ["https://www.google.com/*"],
      "js": ["script.js"],
      "css": ["styles.css"]
    }
  ]
}

在这个示例中，我们定义了一个 content_scripts，并指定了它要注入到哪些页面中。我们还指定了两个文件：一个 JavaScript 文件和一个 CSS 文件，它们将被注入到匹配页面的 DOM 中。

您可以对 content_scripts 进行更复杂的配置，以满足不同的需求。以下是一些可用的字段：

字段名	描述
matches	一个 URL 模式数组，用于匹配要注入脚本和样式表的页面
exclude_matches	一个 URL 模式数组，用于排除某些页面，任何与此模式匹配的页面都不会注入
include_globs 和 exclude_globs	用于进一步细化匹配规则的 glob 模式数组，这些模式应该只匹配相对 URL，而不是完整的绝对 URL
css 和 js	用于指定要注入的 CSS 和 JavaScript 文件的数组，这些文件将按照顺序注入到匹配页面的 DOM 中
run_at	一个字符串，指定代码何时运行。可以设置为 document_start、document_end 或 document_idle。默认值是 document_idle
all_frames	一个布尔值，指示是否应该在所有框架中注入代码。如果设置为 true，代码将在每个子框架中运行一次

需要注意的事项 ⚠️

1. 匹配模式：在定义 matches 字段时，请确保它们能够精确匹配您想要注入代码的页面。否则，您的代码可能会被注入到错误的页面或根本没有注入。
2. 代码性能：由于 content_scripts 中的代码会在每个页面上运行，因此请确保代码非常高效，并尽可能地减少对 DOM 的访问和修改。否则，您的代码可能会导致页面变慢或崩溃。
3. CSS 样式冲突：当您向页面添加自定义 CSS 时，请注意避免与现有样式表发生冲突。如果您的样式表中包含相同的选择器，可能会覆盖页面中的其他样式，导致显示错误。

3. permissions - （必需）声明插件需要访问哪些浏览器资源和 API

permissions 是 manifest.json 文件中的一个必需字段，它主要用于声明插件需要访问哪些浏览器资源和 API。通过使用 permissions 字段，您可以控制插件的能力、限制对用户隐私的访问，并确保插件安全可靠。permissions 是一组字符串数组，每个字符串代表一个权限或 API 名称。它可以控制插件的行为、访问页面内容、访问用户数据等等。以下是一些常见的权限：

字段名	描述
activeTab	允许插件访问当前激活的标签页
storage	允许插件访问浏览器存储（包括本地存储和同步存储）
cookies	允许插件访问浏览器中的 cookie
tabs	允许插件访问浏览器标签页，并执行某些操作（例如打开新标签页、更新标签页 URL、关闭标签页等）
notifications	允许插件创建桌面通知
webNavigation	允许插件在特定的网页事件（例如页面加载、错误和完成等）发生时，获取或修改其信息
identity	允许插件使用 Chrome 身份验证 API，以便用户登录到 Google 帐户
contextMenus	允许插件在浏览器上下文菜单中添加自定义菜单项

现在，我们来看一下如何在 manifest.json 文件中使用 permissions 字段。以下是一个最简单的示例：

{
  "name": "My Extension",
  "version": "1.0",
  "description": "This is my first extension.",
  "permissions": [
    "storage",
    "activeTab"
  ]
}

在这个示例中，我们定义了两个权限：storage 和 activeTab。当用户安装此插件时，Chrome 浏览器将提示用户授权这些权限。如果用户同意，插件就可以访问存储和当前激活的标签页。

需要注意的事项 ⚠️

1. 请求必要的权限：请确保只申请插件所需的权限，并在描述中清晰地解释为什么需要这些权限。不要请求过多的权限，以免使用户感到困扰或担心隐私问题。
2. 安全性：不要将敏感信息存储在插件中，并确保您的代码不会影响用户的安全或隐私。
3. 权限提示：当您的插件需要访问某些权限时，Chrome 浏览器将在安装或更新时提示用户。请确保您的描述清晰明了，并解释为什么需要这些权限。这将帮助用户更好地了解插件的行为和风险。
4. optional_permissions 使用注意：使用 optional_permissions 时，请注意，用户可能会拒绝授权这些权限。因此，请确保在不获得这些权限的情况下，插件仍然可以正常运行，并且不会产生任何错误或负面影响。

4. background - （可选）声明插件需要访问哪些浏览器资源和 API

background 是 manifest.json 文件中的一个字段，用于定义插件的后台页面。通过使用 background 字段，您可以在插件后台运行脚本，并执行各种任务，例如处理请求、与浏览器通信、更新 UI 状态等。

background 的主要作用是启动插件后台页面，并使其一直运行。与 popup 或 options 页面不同，后台页面不会显示给用户。它只是在插件安装或浏览器启动时自动打开，并始终运行在后台。插件可以使用后台页面来监听事件、访问 API、执行操作等等。

常见的一些应用场景包括：

1. 监听事件：插件可以使用后台页面来侦听一些特定的事件（例如网络请求、标签页操作等），并根据需要触发其他操作。
2. 访问 API：插件可以使用后台页面来访问 Chrome 提供的各种 API，例如 storage、tabs、notifications 等等。
3. 执行操作：插件可以使用后台页面来执行一些特定的操作，例如向服务器发送请求、修改标签页内容、获取用户数据等等。
4. 更新状态：插件可以使用后台页面来更新 UI 状态，例如更改图标、显示通知、记录统计信息等等。

除了 scripts 字段之外，background 还支持以下字段：

字段名	描述
persistent	指定后台页面是否应该保持永久运行。如果设置为 false，则后台页面在没有活动的事件处理程序时会自动关闭。默认值为 true
page	指定一个 HTML 页面作为后台页面。如果定义了此字段，则 scripts 字段将被忽略。您可以在该 HTML 页面中包含脚本，以便访问 Chrome API
service_worker	指定一个 Service Worker 脚本作为后台页面。如果定义了此字段，则 scripts 和 page 字段都将被忽略。使用 service_worker 字段时需要注意更多细节

需要注意的事项 ⚠️

1. 后台页面大小限制：由于插件的后台页面始终在编写后台脚本，请注意不要占用过多的系统资源，以免影响用户体验或导致插件崩溃。
2. 脚本加载问题：当插件启动时，Chrome 浏览器将自动加载 background.js 文件。如果您需要在后台页面开始运行之前执行某些初始化操作，则可以使用 chrome.runtime.onStartup() 方法。此方法将在插件安装或浏览器启动时触发。
3. 权限管理问题：如果您的插件需要访问某些特定的 API（例如 tabs、notifications 等），则需要在 manifest.json 文件中声明相应的权限。请确保只申请插件所需的权限，并在描述中清晰地解释为什么需要这些权限。
4. 生命周期问题：当用户关闭浏览器时，后台页面会自动关闭。如果您需要在后台页面关闭之前执行一些操作，请使用 chrome.runtime.onSuspend() 方法。这将在后台页面关闭之前触发，以便您可以保存状态或执行其他清理操作。

---

注意事项

虽然编写 manifest.json 文件非常简单，但有一些需要注意的事项。以下是几个重要的方面：

1.文件名

manifest.json 文件必须以这个特定的名称保存，并且必须位于扩展程序包的根目录下。

2.必填字段

manifest.json 中有一些必填字段，如 name、version 和 manifest_version 等。如果您缺少其中任何一个字段，Chrome 将无法加载您的插件。

3.权限

在 permissions 字段中定义插件需要访问的资源和功能，例如浏览器标签、存储、网络等等。请务必仔细考虑每个权限请求，并确保只申请必要的权限，并在描述中清晰地解释为什么需要这些权限。

4.脚本加载顺序

如果您的插件使用了多个脚本文件，请确保在 manifest.json 中正确指定它们的加载顺序。通常情况下，后台页面和 content_scripts 会优先加载，而浏览器操作按钮和 popup 则会在用户点击时加载。

5.manifest_version

manifest.json 文件必须使用版本号 ，目前只有2个可选值：1和2。

6.不支持注释

在 manifest.json 文件中不能包含注释。如果您需要添加注释，请将其放在单独的文件中并在编译插件之前将其删除或注释掉。

manifest.json 是 Google Chrome 插件开发中非常重要的一个文件，它告诉浏览器如何加载和运行插件，并提供有关插件功能、权限和其他信息的详细说明。在编写 manifest.json 文件时，请务必遵循规范并仔细考虑每个字段的含义。同时，还需要注意一些常见的错误和注意事项，以确保您的插件能够正确地加载和运行，并为用户提供最佳体验。

---

通过本节的讲解，我们了解了manifest.json文件在Chrome插件开发中的重要性和作用。它不仅描述了插件的基本信息，还定义了插件的行为、权限和资源等。我们详细解析了manifest.json文件的结构和每个字段的作用，并分享了一些实用的方法和进阶技巧供读者深入学习和执行。

在插件开发过程中，熟悉和掌握manifest.json文件的配置是至关重要的一步。通过合理配置manifest.json文件，开发者可以实现丰富多样的插件功能，为用户提供更好的浏览器体验。希望本节能帮助您理解manifest.json文件的重要性，并激发对Chrome插件开发的兴趣，进一步探索和创造更多有趣、实用的插件。加油！