ChromeExtensionWizard 实战指南:用 Manifest V3 从零构建高级 Chrome 扩展
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 扩展需求问卷至少应覆盖以下维度:
- 扩展类型:是工具栏弹出面板(action popup)、页面注入脚本(content script)、后台自动化(service worker + 定时任务)、右键菜单(context menu)、Omnibox 命令,还是 DevTools 面板?
- 核心功能:要完成哪一项具体任务?例如"抓取当前页面标题""将选中文本翻译""批量下载图片"——功能描述越具体,permissions 与 API 选择越精准。
- 注入范围:需要在哪些站点上生效?全部
https://*/*、指定域名(如https://github.com/*),还是仅在用户主动点击时注入(activeTab)? - 数据持久化:是否需要保存用户配置或历史数据?由此决定使用
chrome.storage.local还是chrome.storage.sync。 - 交互形态:是否有弹窗 UI、设置页(options page)、通知或徽章(badge)文本?
- 品牌与图标:扩展名称、主色调、图标风格偏好,供后续图标生成使用。
- 发布渠道:目标是 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 列表页与安装确认弹窗。
生成图标时的工程要点:
- 尺寸齐全:
icons字段与action.default_icon中的引用必须真实存在于icons/目录,缺失会导致加载报错; - 格式透明:推荐 PNG,避免使用带透明通道问题的 JPEG;
- 语义一致:图标应体现扩展的核心功能(如翻译工具用语言符号、下载器用箭头),与
name和description呼应; - 风格统一:若扩展有品牌主色,图标、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):
- 使用
idxtool.py --find-gpt GpZaoAfYp可按 GPT ID 在仓库中定位 ChromeExtensionWizard 指令文件; - 使用
gen_gpt_templ.py(基于 Tools/openai_gpts/gen_gpt_templ.py)可从 ChatGPT URL 抓取并生成结构化的 GPT 模板文件,便于批量研究同类助手; - 仓库 CustomInstructions/README.md 收录了 1573 个 ChatGPT GPT 指令,可横向对比 ChromeExtensionWizard(高级向)与 Chrome Dev Buddy(入门向)的措辞差异,观察同一技术主题下指令的分层设计。
八、总结与可复用清单
ChromeExtensionWizard 的核心价值不在"会写代码",而在于把 Chrome 扩展开发固化成一条可复述、可执行、可复用的方法论流水线:
- 问卷先行:用结构化问卷把"模糊想法"收敛为可编码需求;
- 骨架复用:基于 Manifest V3 输出标准工程结构,保证代码可直接落地;
- 权限精确:由需求驱动的最小权限声明,兼顾功能完整与审核合规;
- 资产完整:图标、样式与功能语义一致,交付物可直接加载调试;
- 人格适配:"professional yet kind"的交互定位,让高级能力与友好体验并存。
对你而言,这套方法论同样适用于自己动手开发扩展:先在 chrome://extensions 打开"开发者模式",点击"加载已解压的扩展程序"选择项目目录即可调试;manifest_version 固定为 3,所有配置以本节清单为准。它既是一份 GPT 指令的解读,更是一份可以直接照做的 Manifest V3 开发速查手册。