ChromeExtensionWizard 实战指南:用 Manifest V3 从零构建高级 Chrome 扩展

原创2026-10-16 07:52:051,631 阅读
文章标签:提示工程人工智能大模型AI 安全治理提示词注入防护文档技术博客

ChromeExtensionWizard 实战指南:用 Manifest V3 从零构建高级 Chrome 扩展

本篇技术指南围绕 TheBigPromptLibrary 仓库中收录的 ChromeExtensionWizard 自定义指令,解析这一面向高级 Chrome 扩展开发的 GPT 助手所依赖的完整工作流:Manifest V3 工程骨架、结构化需求问卷、可复用 boilerplate 代码与自定义图标生成。读完本文,你将掌握一套可复制的「需求采集 → 工程初始化 → 核心功能编码 → 图标与发布」开发路径,并了解如何把这类 GPT 指令当作可研究、可复用的开发方法论模板。

一、ChromeExtensionWizard 是什么

该 GPT 的官方指令原文如下(收录于 CustomInstructions/ChatGPT/GpZaoAfYp_ChromeExtensionWizard.md):

ChromeExtensionWizard is a professional yet kind GPT that assists in building advanced Chrome Extensions using the manifest v3 format. It provides detailed boilerplate code, uses a structured questionnaire to gather project details, and generates custom icons. This GPT is designed to support a wide range of extension types and ensures a friendly, approachable interaction with users, catering to their specific needs and visions for their extensions.

从这段指令可以提炼出它的四大核心设计:

能力要素 指令原文依据 落地形态
技术基准 "using the manifest v3 format" 所有代码输出均遵循 Manifest V3 规范
代码交付 "provides detailed boilerplate code" 直接给出可复制、可运行的工程骨架
需求采集 "uses a structured questionnaire" 通过结构化问卷收敛项目细节
视觉资产 "generates custom icons" 为扩展生成定制图标

值得注意的是,在仓库的 GPT 目录下还有一个面向初学者的同主题 GPT —— Chrome Dev Buddy,其指令同样强调 "focusing on manifest version 3.0",但定位是"用简单语言、逐步骤讲解、避免专业术语"。二者形成互补:Chrome Dev Buddy 负责零基础入门,ChromeExtensionWizard 负责高级工程落地。这种"同一技术主题、不同目标用户、不同指令写法"的组合,本身就是研究 GPT 指令设计风格的绝佳样本。

二、需求采集:结构化问卷的提问维度设计

ChromeExtensionWizard 强调"uses a structured questionnaire to gather project details",这意味着它在动手写代码前,会先以问卷形式收敛需求。从工程实践角度,一套合格的 Chrome 扩展需求问卷至少应覆盖以下维度:

  1. 扩展类型:是工具栏弹出面板(action popup)、页面注入脚本(content script)、后台自动化(service worker + 定时任务)、右键菜单(context menu)、Omnibox 命令,还是 DevTools 面板?
  2. 核心功能:要完成哪一项具体任务?例如"抓取当前页面标题""将选中文本翻译""批量下载图片"——功能描述越具体,permissions 与 API 选择越精准。
  3. 注入范围:需要在哪些站点上生效?全部 https://*/*、指定域名(如 https://github.com/*),还是仅在用户主动点击时注入(activeTab)?
  4. 数据持久化:是否需要保存用户配置或历史数据?由此决定使用 chrome.storage.local 还是 chrome.storage.sync。
  5. 交互形态:是否有弹窗 UI、设置页(options page)、通知或徽章(badge)文本?
  6. 品牌与图标:扩展名称、主色调、图标风格偏好,供后续图标生成使用。
  7. 发布渠道:目标是 Chrome Web Store 上架、企业内部分发(Enterprise Policy),还是本地开发者模式加载?

问卷的收口价值在于:每个答案都能直接映射到 manifest.json 中的一个字段或一组 API。例如"需要跨页面保存设置"→ 声明 "permissions": ["storage"];"只在用户点击工具栏按钮时操作当前标签页"→ 使用 "permissions": ["activeTab"] 而非宽泛的 host_permissions,以最小权限原则降低审核风险。

三、Manifest V3 工程骨架:核心 Boilerplate 代码

ChromeExtensionWizard 承诺"provides detailed boilerplate code",其输出基准是 Manifest V3。以下是符合该规范的标准工程结构:

my-extension/
├── manifest.json
├── background.js          # service worker 后台脚本
├── popup/
│   ├── popup.html
│   ├── popup.css
│   └── popup.js
├── content/
│   ├── content.js         # 注入到目标页面的脚本
│   └── content.css
├── options/
│   ├── options.html       # 设置页(可选)
│   └── options.js
└── icons/
    ├── icon16.png
    ├── icon32.png
    ├── icon48.png
    └── icon128.png

3.1 manifest.json —— 一切的入口

{
  "manifest_version": 3,
  "name": "My Advanced Extension",
  "version": "1.0.0",
  "description": "An example extension scaffolded by ChromeExtensionWizard-style workflow",
  "icons": {
    "16": "icons/icon16.png",
    "32": "icons/icon32.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },
  "action": {
    "default_popup": "popup/popup.html",
    "default_title": "My Extension",
    "default_icon": {
      "16": "icons/icon16.png",
      "32": "icons/icon32.png"
    }
  },
  "background": {
    "service_worker": "background.js"
  },
  "content_scripts": [
    {
      "matches": ["https://*/*", "http://*/*"],
      "js": ["content/content.js"],
      "css": ["content/content.css"],
      "run_at": "document_idle"
    }
  ],
  "permissions": ["storage", "scripting", "activeTab"],
  "host_permissions": ["https://*/*"],
  "options_page": "options/options.html",
  "commands": {
    "toggle-feature": {
      "suggested_key": { "default": "Ctrl+Shift+Y" },
      "description": "Toggle the extension feature"
    }
  }
}

关键字段说明:

  • manifest_version 固定为 3,这是本指令的技术基准,也决定了整个代码形态;
  • background.service_worker 取代了 Manifest V2 的 background.scripts,扩展后台改为事件驱动的 Service Worker,不能长期驻留,需依赖事件注册(onInstalled、onMessage、onAlarm、commands.onCommand 等)唤醒;
  • action 定义工具栏图标与弹出面板,default_popup 指向 HTML 文件;
  • content_scripts 以 matches 限定注入站点,run_at: "document_idle" 表示在 DOM 加载完成后注入,是多数场景的推荐时机;
  • permissions 与 host_permissions 分离:前者声明扩展自身可用的 API,后者声明可访问的站点——二者合起来构成扩展的权限边界,应遵循最小授权原则。

3.2 background.js —— Service Worker 事件驱动

// background.js —— MV3 事件驱动后台脚本
chrome.runtime.onInstalled.addListener(() => {
  console.log("Extension installed:", chrome.runtime.getManifest().name);
});

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === "fetch-page-title") {
    // 从 content script 转发而来的请求,可在此调度 API 调用
    sendResponse({ ok: true, title: sender.tab?.title ?? "" });
  }
  return true; // 保持消息通道,支持异步响应
});

chrome.commands.onCommand.addListener((command) => {
  if (command === "toggle-feature") {
    console.log("Keyboard shortcut triggered");
  }
});

与 Manifest V2 的常驻 background page 不同,MV3 的 service worker 会在空闲后终止。因此,任何需要"记住"的状态都应落到 chrome.storage,而不是进程内全局变量。

3.3 popup 与 content script 的典型交互

popup/popup.js —— 读取并保存配置:

// popup.js
document.addEventListener("DOMContentLoaded", async () => {
  const { keyword = "default" } = await chrome.storage.sync.get("keyword");
  document.querySelector("#keyword").value = keyword;
});

document.querySelector("#save").addEventListener("click", async () => {
  const keyword = document.querySelector("#keyword").value;
  await chrome.storage.sync.set({ keyword });
  // 通知 content script 使用最新配置
  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
  chrome.tabs.sendMessage(tab.id, { type: "config-updated", keyword });
});

content/content.js —— 在目标页面执行注入逻辑:

// content.js —— 注入到匹配页面
chrome.runtime.onMessage.addListener((message) => {
  if (message.type === "config-updated") {
    applyConfig(message.keyword);
  }
});

function applyConfig(keyword) {
  document.title = `${keyword} | ${document.title}`;
}

这套「popup 收配置 → storage 持久化 → content script 消费配置」的三角链路,是绝大多数交互型扩展的通用范式,也正是结构化问卷收敛出的需求在代码层面的直接投影。

四、权限模型:从问卷答案到 manifest 声明的映射

Manifest V3 权限声明的核心取舍是 activeTab、scripting 与 host_permissions 的组合:

问卷答案 推荐的权限声明 理由
"只在用户点击按钮时操作当前页" "permissions": ["activeTab"] 临时授权当前标签页,无需申请全域访问
"需要在多个站点自动执行脚本" content_scripts.matches 精确列出域名 声明式注入,由浏览器按匹配规则执行
"需要在用户点击后向页面动态注入脚本" "permissions": ["scripting"] + host_permissions 通过 chrome.scripting.executeScript 动态注入
"需要保存用户设置并跨设备同步" "permissions": ["storage"] chrome.storage.sync 随 Google 账户同步
"需要向外部 API 发起跨域请求" host_permissions 声明目标 API 域 替代 V2 的 XHR 免声明特权

从 Chrome Web Store 的审核实践看,权限声明必须与实际功能一一对应。ChromeExtensionWizard 的"professional"定位正体现在这一层:它不会为了省事给扩展加上全域 host_permissions,而是依据问卷答案做最小化配置。

五、自定义图标生成:从视觉需求到扩展资产

指令中的 "generates custom icons" 对应扩展的图标资产需求。Chrome 扩展至少需要四档图标尺寸,分别用于工具栏、扩展管理页与商店展示:

  • 16×16:浏览器工具栏、右键菜单显示;
  • 32×32:高 DPI 工具栏显示;
  • 48×48:扩展管理页(chrome://extensions)列表;
  • 128×128:Chrome Web Store 列表页与安装确认弹窗。

生成图标时的工程要点:

  1. 尺寸齐全:icons 字段与 action.default_icon 中的引用必须真实存在于 icons/ 目录,缺失会导致加载报错;
  2. 格式透明:推荐 PNG,避免使用带透明通道问题的 JPEG;
  3. 语义一致:图标应体现扩展的核心功能(如翻译工具用语言符号、下载器用箭头),与 name 和 description 呼应;
  4. 风格统一:若扩展有品牌主色,图标、popup 背景与选项页样式应保持一致,形成整体视觉识别。

对 GPT 助手而言,"生成图标"既可借助图像生成能力产出概念稿,也可直接输出可执行的图标规格清单,交由设计工具完成最终切图。

六、面向多种扩展类型的适配策略

"designed to support a wide range of extension types" 意味着该工作流不是单一模板,而是可按类型切换骨架。常见类型与对应技术选型如下:

扩展类型 核心入口 典型 API
工具栏工具(翻译、截图、笔记) action + popup chrome.tabs、chrome.scripting、chrome.storage
页面增强(阅读模式、广告样式修正) content_scripts DOM 操作 + matches 精确限定
后台自动化(价格监控、定时任务) background.service_worker chrome.alarms、chrome.notifications、fetch
右键增强(选中文本处理) context menu chrome.contextMenus
地址栏命令 Omnibox chrome.omnibox
开发者工具 DevTools 面板 chrome.devtools.panels、chrome.devtools.network
新标签页美化 override 页面 chrome_url_overrides.newtab

问卷中"扩展类型"这一项的选择,会直接决定 boilerplate 采用哪一套入口文件组合。这也是该 GPT 能"覆盖广"而非"样样浅"的关键:类型决定骨架,功能决定 API,站点决定权限。

七、在仓库中研究与管理此类 GPT 指令

TheBigPromptLibrary 提供了完整的工具链用于研究这类指令文件本身(见 Tools/openai_gpts/README.md):

八、总结与可复用清单

ChromeExtensionWizard 的核心价值不在"会写代码",而在于把 Chrome 扩展开发固化成一条可复述、可执行、可复用的方法论流水线:

  1. 问卷先行:用结构化问卷把"模糊想法"收敛为可编码需求;
  2. 骨架复用:基于 Manifest V3 输出标准工程结构,保证代码可直接落地;
  3. 权限精确:由需求驱动的最小权限声明,兼顾功能完整与审核合规;
  4. 资产完整:图标、样式与功能语义一致,交付物可直接加载调试;
  5. 人格适配:"professional yet kind"的交互定位,让高级能力与友好体验并存。

对你而言,这套方法论同样适用于自己动手开发扩展:先在 chrome://extensions 打开"开发者模式",点击"加载已解压的扩展程序"选择项目目录即可调试;manifest_version 固定为 3,所有配置以本节清单为准。它既是一份 GPT 指令的解读,更是一份可以直接照做的 Manifest V3 开发速查手册。

登录后查看全文
TheBigPromptLibrary