Chrome 扩展开发速查
版本unknown 更新日志2025-11-24 GitHubGoogleChrome/chrome-extensions-samples
360px

Manifest 结构速览 键清单

键说明
manifest_version唯一支持值为 3，开启 MV3 事件驱动与安全沙箱。
name/version/description在Chrome商店与扩展管理页展示；name 限 75 字，description 限 132 字，建议配合 default_locale 进行国际化。
icons至少提供 48px 与 128px，供工具栏、Chrome Web Store 及扩展页使用。
action/background/service_worker定义工具栏入口与后台事件逻辑；MV3 仅支持 service_worker，persistent 无效。
permissions / host_permissionspermissions 关联 API 权限（如 tabs/storage），host_permissions 定义可访问的 URL 匹配；建议使用 optional_* 逐步请求。
content_scripts / web_accessible_resources声明注入脚本与可被网页读取的资源，需同时提供 matches、js/css 与 run_at。
cross_origin_embedder_policy / cross_origin_opener_policy设置 COEP/COOP（credentialless/same-origin）以启用 SharedArrayBuffer 与跨源通信。
declarative_net_request静态规则描述，traceable 但性能友好；可搭配 dynamic_rules 实现运行期更新。
{
  "manifest_version": 3,
  "name": "Chrome 扩展速查",
  "version": "1.0",
  "description": "界面、网络与通信指南",
  "icons": {
    "16": "images/icon-16.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "action": { "default_popup": "popup.html" },
  "background": { "service_worker": "service-worker.js" },
  "permissions": ["storage", "tabs", "scripting"],
  "host_permissions": ["https://*.example.com/*"],
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "js": ["content.js"],
      "run_at": "document_idle"
    }
  ]
}

Service Worker / 生命周期

  • chrome.runtime.onInstalled 处理首次安装、本地数据迁移与版本升级提示；搭配 runtime.setUninstallURL 可收集反馈。
  • chrome.runtime.onStartup 在用户打开 Chrome 时唤醒，可校验同步配置或调用 API 拉取更新。
  • chrome.runtime.onSuspend 发生在 Service Worker 闲置前，需快速清理定时器并保存必要状态。
  • chrome.alarms 是唤醒 Service Worker 的可靠方式；建议与 chrome.alarms.get 校验重复任务。
  • 避免在 Service Worker 中直接操作 DOM；需 UI 时迁移至 popup/sidePanel 或通过 Offscreen Document。

界面入口与交互

  • chrome.action 控制工具栏图标、徽章、popup；结合 setBadgeText 与 setIcon 提示状态。
  • Popup/Options/DevTools Panel/Sidebar 为 HTML 页面，建议复用样式变量并使用 template 组件提升维护性。
  • chrome.sidePanel 适用于旁栏常驻内容，重点是保持页面轻量与可滚动；使用 default_path 指向静态页面。
  • chrome.contextMenus 与 chrome.commands 为场景提供快捷入口，事件回调中可调用 chrome.runtime.sendMessage 触发后端逻辑。
  • Popup 与 Content Script 之间的消息通信必须通过 chrome.runtime.sendMessage/chrome.tabs.sendMessage，避免直接访问 DOM。

浏览器与网络控制

  • chrome.tabs 提供 query/create/update/remove/duplicate，`captureVisibleTab` 可截图；`scripting.executeScript` 替代已废弃的 `tabs.executeScript`。
  • chrome.windows 用于创建、聚焦、同步窗口状态；chrome.sessions 支持会话恢复。
  • 内容脚本与 scripting.executeScript 配合：通过 `matches` + `run_at` 控制代码注入时机，`world` 可设置为 ISOLATED 或 MAIN。
  • declarativeNetRequest 用于静态/动态规则过滤；仅在必须时再申请 `webRequest` 权限。
  • chrome.contentSettings 与 chrome.cookies 管控 Cookie/JavaScript/弹窗等行为；chrome.proxy 辅助重写网络策略。

权限与安全 权限警告

  • permissions 定义可访问的 API，host_permissions 控制 Web 请求范围；在 Manifest 中将高风险权限分组并尽量交给 optional_permissions 请求。
  • 部分权限会触发警告：如 cookies、history、tabs（读取浏览记录）、declarativeNetRequest（屏蔽所有页面）、proxy、webRequestBlocking。
  • activeTab 通过点击等用户手势临时授予当前标签页访问权限，是减少权限的首选。
  • MV3 禁止 eval 与 remote code，所有脚本需打包并使用 CSP；建议设置 `content_security_policy` 严格模式。
  • 配置 COOP/COEP（credentialless/same-origin） + Offscreen Document，解决 Service Worker 无 DOM 的限制。

存储、通信与调试

  • Storage：`sync`（跨设备）、`local`（本地）、`managed`（企业）、`session`（标签页生命周期）；`chrome.storage.onChanged` 实时监听。
  • 消息机制：Popup、Content Script、Service Worker 通过 `runtime.sendMessage`/`tabs.sendMessage`、`runtime.connect` 与 `Port` 互通；推荐在 background 中缓存 listener。
  • chrome.commands` 快捷键可直接在 Service Worker 中触发 `scripting.executeScript` 或写入 `storage.session`。
  • 调试手段：开启 `chrome://extensions` 开发者模式，使用 `service_worker` 控制台、`chrome://inspect/#service-worker` 追踪事件。
  • chrome.runtime.onUpdateAvailable` 与 `chrome.runtime.reload` 组合实现更新推送；`chrome.runtime.getPlatformInfo` 辅助多平台提示。