Chrome 扩展

Chrome 扩展运行在浏览器提供的扩展平台中，用于向网页或浏览器界面增加功能。新项目使用 Manifest V3（MV3）。扩展包的根目录必须包含 manifest.json，其中 manifest_version、name 和 version 为必填项。

最小结构

chrome-extension/
├── manifest.json
├── popup.html
├── popup.js
├── service-worker.js
├── content.js
└── icons/

{
  "manifest_version": 3,
  "name": "示例扩展",
  "version": "1.0.0",
  "description": "扩展功能说明",
  "icons": {
    "16": "icons/icon-16.png",
    "48": "icons/icon-48.png",
    "128": "icons/icon-128.png"
  },
  "action": {
    "default_popup": "popup.html"
  }
}

action 定义工具栏入口。设置 default_popup 后，点击工具栏图标会打开弹窗；未设置时，可在 service worker 中监听 chrome.action.onClicked。

权限与匹配范围

扩展权限分为 API 权限与站点访问权限：

• permissions：声明扩展 API，例如 storage、scripting、alarms、tabGroups。
• host_permissions：声明可访问或注入的站点范围，例如 https://example.com/*。
• activeTab：用户主动点击扩展后，临时访问当前标签页；适合按需执行的功能。

按最小权限原则声明，不要使用宽泛的匹配规则来替代实际需要的域名。

{
  "permissions": ["activeTab", "scripting"],
  "host_permissions": ["https://developer.chrome.com/*"]
}

内容脚本

content_scripts 会在 URL 匹配时自动注入 JavaScript 或 CSS。它适合读取、标注或修改页面内容。

{
  "content_scripts": [
    {
      "matches": ["https://example.com/articles/*"],
      "js": ["content.js"],
      "css": ["content.css"],
      "run_at": "document_idle"
    }
  ]
}

内容脚本与页面脚本处于隔离执行环境，不能直接共享 JavaScript 变量；需要跨上下文协作时使用消息通信。

开发与调试

1. 打开 chrome://extensions，开启开发者模式。
2. 选择“加载已解压的扩展程序”，指定包含 manifest.json 的目录。
3. 修改 manifest、service worker 或内容脚本后，在扩展卡片上重新加载。
4. 分别通过扩展卡片的 service worker 检查入口、popup 的开发者工具和目标页面的开发者工具排查不同上下文的问题。

注意事项

• MV3 使用事件驱动的 service worker，不使用长期运行的后台页面。
• 扩展包中的脚本应随安装包发布；不要从远程地址加载并执行 JavaScript。
• 发布前检查名称、描述、图标、权限说明及隐私处理是否与实际功能一致。

参考：Manifest 文件格式、MV3 概览。