OneYoung

Appearance

本节介绍一下从零到一创建一个 Chrome Extension。

官方文档：手把手创建一个Chrome Extension

My suck source code: learn-web-extensions

1.1 manifest.json ​

manifest.json 文件实际上是 chrome 扩展的配置清单，它定义了的扩展程序的元数据（比如名称、版本）和主要功能（比如 content script、background service worker、action、commands 等）。

json
{
  "name": "Hello Extensions of the world!",
  "description": "Base Level Extension",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    // "default_popup": "src/hello.html", // 与chrome.action.onClicked.addListener冲突
    "default_icon": "src/assets/images/icon.png"
  },
  "icons": {
    "16": "src/assets/images/icon-16.png",
    "32": "src/assets/images/icon-32.png",
    "48": "src/assets/images/icon-48.png",
    "128": "src/assets/images/icon-128.png"
  },
  "content_scripts": [
    {
      "js": ["src/scripts/content.js"],
      "matches": [
        "https://developer.chrome.com/docs/extensions/*",
        "https://developer.chrome.com/docs/webstore/*",
        "https://developer.chrome.com/docs/extensions/reference/*"
      ]
    }
  ],
  "background": {
    // "service_worker": "src/scripts/background.js",
    "service_worker": "src/scripts/service-worker.js",
    "type": "module"
  },
  "permissions": ["activeTab", "scripting", "storage", "alarms"],
  "host_permissions": ["https://chrome.dev/f/*"],
  "commands": {
    "_execute_action": {
      "suggested_key": {
        "default": "Ctrl+B",
        "mac": "Command+B"
      }
    }
  },
  "minimum_chrome_version": "102",
  "omnibox": {
    "keyword": "api"
  }
}

1.2 字段详解 ​

1.2.1 name ​

json
"name": "Hello Extensions of the world!"

✅ 作用: 扩展在 chrome://extensions页面和浏览器菜单中展示时所使用的名称。

1.2.2 description ​

json
"description": "Base Level Extension"

✅ 作用: 对扩展进行简要地功能和用途说明，帮助用户了解你的扩展。

1.2.3 version ​

json
"version": "1.0"

✅ 作用: 扩展的版本号，推荐使用语义化版本（ SemVer ，如 1.0.0），随着扩展功能的推进可以进行增量。

1.2.4 manifest_version ​

json
"manifest_version": 3

✅ 作用: 指定 manifest 文件所适用的版本，新版扩展均需要设置为 3，它对整体结构和API有重大调整（包括 service worker 取代 background page 等）。

1.2.5 action ​

json
"action": {
  "default_icon": "src/assets/images/icon.png"
}

✅ 作用: 定义浏览器工具栏上扩展按钮（action）的设置，如：

  • default_icon: 设置 toolbar 上展现出的图标。

✅ 小Tip: 可以配置 default_popup 来为 button 设置一个弹出页面，但是此项目中已被注释掉，因为它与 chrome.action.onClicked 事件发生冲突。

1.2.6 icons ​

json
"icons": {
  "16": "src/assets/images/icon-16.png",
  "32": "src/assets/images/icon-32.png",
  "48": "src/assets/images/icon-48.png",
  "128": "src/assets/images/icon-128.png"
}

✅ 作用: 定义不同尺寸下扩展所使用的 icon，建议准备 16, 32, 48, 128 四种尺寸。

1.2.7 content_scripts ​

json
"content_scripts": [
  {
    "js": ["src/scripts/content.js"],
    "matches": [
      "https://developer.chrome.com/docs/extensions/*",
      "https://developer.chrome.com/docs/webstore/*",
      "https://developer.chrome.com/docs/extensions/reference/*"
    ]
  }
]

✅ 作用: 指定哪个 JavaScript 文件（通常为 content script）需要自动插入到哪个页面中。

✅ matches: 是一个 URL pattern 列表，只有匹配到它时，扩展才会自动插入对应的 script。

1.2.8 background ​

json
"background": {
  "service_worker": "src/scripts/service-worker.js",
  "type": "module"
}

✅ 作用: 定义 扩展的 service worker（由 MV3 取代 MV2 的 background page），负责处理长时事件，如 alarm、message 等。

✅ type: "module" 让 service worker 能使用 ES Module语法（import/export）。

1.2.9 permissions ​

json
"permissions": ["activeTab", "scripting", "storage", "alarms"]

✅ 作用: 列出扩展需要获得的权限，只有申请到许可后，扩展可以：

  • activeTab: 访问当前标签页。
  • scripting: 动态地插入/移除脚本。
  • storage: 读写 chrome.storage。
  • alarms: 设置周期性的 alarm 事件。

1.2.10 host_permissions ​

json
"host_permissions": ["https://chrome.dev/f/*"]

✅ 作用: 赋予扩展可以对指定域进行操作，如可以对 https://chrome.dev/f/* 下的页面进行操作。

1.2.11 commands ​

json
"commands": {
  "_execute_action": {
    "suggested_key": {
      "default": "Ctrl+B",
      "mac": "Command+B"
    }
  }
}

✅ 作用: 为扩展定义快捷键，_execute_action 是保留字，按下此快捷时，会触发 chrome.action，比如可以打开弹出页面。

1.2.12 minimum_chrome_version ​

json
"minimum_chrome_version": "102"

✅ 作用: 指定你的扩展需要哪个最少版本的 Chrome 才能正常工作。

1.2.13 omnibox ​

json
"omnibox": {
  "keyword": "api"
}

✅ 作用: 配置扩展可以在 omnibox（浏览器顶部的输入框） 中进行交互， 其中 keyword 是触发关键字，输入 api （后有空格）时，会进入扩展提供的建议模式。

🔹整体总结 ​

✅ manifest.json 是每一个 Chrome 扩展必需且最重要的配置文件。

✅ 每一个字段均有具体作用，帮助浏览器了解你的扩展：

  • 需要哪个权限
  • 有哪个 UI 入口（action）
  • 有哪个 service worker 在后台处理事件
  • 有哪个 content script 注入到哪个页面中
  • 有哪个快捷方式可以调起它

✅ MV3 较 MV2 有重大改动，如：

  • background page 已经被 service worker 取代
  • manifest_version 需要设置为 3
  • 权限需要更细粒度地配置（permissions vs host_permissions）

1.3 本地调试 ​

Debug

在开发者模式下加载未封装的扩展程序，请执行以下操作：

  1. 在新标签页中输入 chrome://extensions 即可前往“扩展程序”页面。（根据设计，chrome:// 网址不可链接。） 或者，点击“扩展程序”菜单拼图按钮，然后选择菜单底部的管理扩展程序。 或者，点击 Chrome 菜单，将鼠标悬停在更多工具上，然后选择扩展程序。
  2. 点击开发者模式旁边的切换开关，即可启用开发者模式。
  3. 点击加载已解压缩的文件按钮，然后选择扩展程序目录。