SuperAPI AI 工具集

chrome-extension

编程与开发

查看项目

更新于 10-16 10:14

技能介绍

用途

本技能用于构建、调试与发布基于 Manifest V3 的 Chrome 浏览器扩展(Chrome Extension)。它采用路由文档的组织方式:先阅读主文件以理解整体架构与决策点,然后针对当前任务加载对应的自包含参考文件获取实现细节,无需通读全部内容。

主要能力

技能覆盖以下主题,分别对应独立参考文件:

  • manifest-v3:设置或修改 manifest.json、配置图标、版本管理
  • service-worker:后台逻辑、生命周期、状态持久化、alarms、事件
  • content-scripts:向页面注入代码、隔离世界/主世界、动态注入、SPA 处理、孤立(orphaning)问题
  • messaging-rpc:各上下文之间的通信、类型化协议、RPC 层、异步处理器模式
  • ui-surfaces:弹窗、选项页、侧边栏、右键菜单、命令、通知、omnibox、devtools 面板
  • storage:chrome.storage(local/sync/session)、配额、响应式模式、框架 hooks
  • network-csp:内容脚本发起 HTTP 请求、CSP 绕过中继、declarativeNetRequest、离屏文档、CORS
  • permissions:必需/可选权限、host 权限、activeTab、运行时请求流程
  • web-accessible-resources:向网页暴露扩展文件及其安全影响
  • typescript-build:TypeScript 配置、项目结构、构建工具对比、打包
  • publishing:Chrome Web Store 提交、审核流程、常见拒绝原因、更新、隐私政策
  • execution-contexts:通信流程图、各上下文能力与限制、如何选择正确的消息方式
  • debugging-mistakes:扩展用 DevTools、测试 Service Worker 终止、常见陷阱与错误模式

核心架构

一个 Chrome 扩展最多有 5 个执行上下文,通过消息传递通信:扩展进程内的 Service Worker(无 DOM、短暂存活、可用全部 chrome.* API)、Popup、Options Page、Side Panel(三者均有完整 DOM 与全部 API);以及网页侧的内容脚本(隔离世界,共享 DOM,拥有独立 JS 作用域,可用 chrome.runtime 与 chrome.storage,受页面 CSP 网络限制)和主世界脚本(页面上下文,无 chrome.* API,受完整 CSP 限制),二者通过 window.postMessage 通信。

关键架构规则

  • Service Worker 是短暂的,30 秒无活动即终止;所有状态须持久化到 chrome.storage;所有事件监听器须在顶层同步注册;不要用 setTimeout/setInterval 处理超过几秒的任务。
  • 内容脚本运行在页面源下,其网络请求受页面 CSP 与 CORS 约束,需绕过时通过 Service Worker 中继。
  • 消息传递是骨干,每个跨上下文交互都使用 chrome.runtime 消息;最常见 bug 是异步消息监听器忘记 return true。
  • 权限决定 CWS 审核速度:宽泛的 host_permissions 会触发人工审核(数周),activeTab + 可选权限则可快速自动审核。
  • Popup 失焦即销毁,Side Panel 持久存在,按交互时长选择。

使用方式

技能提供两种工作流:

  1. 从零新建扩展:先定义带最小权限的 manifest(从 activeTab + scripting 起步),配置 TypeScript 与构建工具(或使用 CRXJS for Vite),在顶层实现 Service Worker 事件监听器,按需添加内容脚本,构建 UI 界面,串联各上下文消息,用 DevTools 测试(尤其测试 Service Worker 终止),最后发布。
  2. 为现有扩展增加功能:先判断功能属于哪个上下文,阅读对应参考文件,检查是否需要新权限(优先可选权限),更新 manifest,并妥善处理扩展更新时的内容脚本孤立问题。

适用场景

技能包含决策树帮助判断由哪个上下文处理任务,例如:需要用户访问页面时运行代码、需要向自建 API 发请求、需要存储用户设置、需要修改 HTTP 头或拦截请求、需要页面 JS 与扩展通信、需要周期性后台任务、需要在后台使用 DOM API、需要 OAuth 认证等。

限制与注意事项

  • 禁止使用 eval()、new Function() 或加载远程脚本(MV3 不允许)。
  • 不要用 setTimeout/setInterval 处理 Service Worker 中超过 5 秒的任务。
  • 不要在回调或异步函数内部注册事件监听器。
  • 除绝对必要外不要使用 <all_urls> host 权限。
  • 测试时不要依赖 DevTools 保持 Service Worker 存活。
  • 异步消息监听器不要忘记 return true。
  • 不要在 Service Worker 中使用 localStorage 或 sessionStorage(不存在)。
  • 不要假设内容脚本能在扩展更新后存活。
  • 不要使用 webRequest 拦截(MV3 已移除),改用 declarativeNetRequest。
  • 不要使用 chrome.extension.getBackgroundPage()(MV3 已移除)。

关于收费、价格等信息暂未提供。