浏览器扩展样板代码生成器 - 定制 manifest 与脚本

Manifest V3 是 Chrome 浏览器扩展的最新规范版本，相比 V2 有几项重大变更：后台脚本从 Background Page 改为 Service Worker，后者在空闲时会自动终止，需要通过 chrome.storage 保存状态、chrome.alarms 实现周期任务；browser_action 和 page_action 合并为统一的 action API；主机权限从 permissions 中独立为 host_permissions 字段；限制了远程代码执行，禁止在扩展中加载外部 JavaScript 文件。V2 已于 2025 年逐步淘汰，Chrome Web Store 不再接受新的 V2 扩展提交。建议所有新项目默认使用 V3 版本开发，本工具支持一键切换 V2 和 V3，自动生成对应规范的配置文件。

Content Script 运行在网页的 DOM 环境中，可以读取和修改页面内容，常见功能包括：注入自定义 UI 元素（如浮动操作按钮、信息侧边栏、自定义工具栏）；提取页面数据（如商品价格、文章正文、表格数据）；修改页面样式和行为（如去除广告元素、调整排版布局、添加快捷键支持）；监听 DOM 变化并响应特定事件（如页面滚动、表单提交）。需要注意的是，Content Script 运行在隔离的 JavaScript 环境中，无法直接访问网页的 window 对象和网页自身注入的 JavaScript 变量。与 Background 通信需通过 chrome.runtime.sendMessage API。本工具的 Content Script 配置支持 URL 匹配模式（matches 字段）和自定义代码输入。

Chrome 浏览器提供完善的扩展调试工具：首先打开 chrome://extensions/ 页面并开启右上角的「开发者模式」开关。Background 的 Service Worker 可通过扩展详情页中的「检查视图」链接打开独立的开发者工具控制台，查看后台日志和网络请求；Popup 弹窗可在扩展图标上右键选择「检查」打开调试窗口，实时查看 HTML 渲染和 JavaScript 执行情况；Content Script 的日志输出在网页自身的控制台中查看（F12 或右键检查），需要注意区分扩展注入的 Content Script 日志和网页自身脚本的日志。建议在开发过程中保持开发者模式开启，实时查看运行日志和错误信息，使用断点调试定位问题。

Chrome Web Store 审核对权限声明有严格要求，以下是关键注意事项：扩展只应申请功能必需的权限，过多权限会导致审核失败或被标记为高风险应用；activeTab 权限仅在用户点击扩展图标时临时激活当前标签页，比 tabs 权限（可访问和操作所有标签页列表）更受审核推荐；Host 权限应尽量使用具体的域名模式（如 https://www.example.com/*），避免使用 <all_urls> 通配符，宽泛的主机权限需要在商品描述中详细说明用途；敏感权限如 webRequest（网络拦截）、clipboardWrite（剪贴板写入）需要在商品详情页中明确说明使用场景。本工具根据启用的组件类型自动推荐必要权限，帮助开发者遵循最小权限原则。

Manifest V3 的 Service Worker 生命周期与传统后台页面有本质区别：安装后不会立即启动，而是在首次需要时（如事件触发、用户操作）启动；空闲约 30 秒后会自动终止以节省系统资源；浏览器重启后需要重新启动。由于 Service Worker 随时可能被终止，不能依赖全局变量保存任何状态。应使用 chrome.storage.local API 将状态持久化到磁盘，每次启动时从存储中恢复。对于需要周期性执行的任务，使用 chrome.alarms API 设置定时器，可以在 Worker 终止后按计划唤醒执行。另外，chrome.storage.session 适合保存仅在浏览器运行期间有效的临时状态。本工具在权限配置中提供 storage 和 alarms 选项，方便开发者实现状态管理和定时任务功能。

发布扩展到 Chrome Web Store 需要完成以下步骤：首先访问 Chrome 开发者控制台（https://chrome.google.com/webstore/devconsole）注册开发者账号，需支付一次性注册费约 5 美元；然后将项目目录打包为 ZIP 文件，确保 manifest.json 位于 ZIP 包的根目录位置；在控制台点击「新建商品」按钮上传 ZIP 包；填写商品名称、简短描述和详细描述、至少一张 1280x800 像素的宣传截图、隐私政策页面链接等信息；配置商品可见性（公开或限定地区）和定价信息；最后点击提交审核，审核周期通常为 1-3 个工作日。审核通过后扩展即可在 Chrome Web Store 上架供用户安装。Edge 浏览器使用 Microsoft Add-ons 商店，Firefox 使用 addons.mozilla.org，各自有独立的发布流程和审核要求。

工具生成的代码是符合浏览器扩展规范的标准模板，可以直接作为项目起点使用，但生产环境发布前建议进行以下检查和完善：根据实际功能需求补充业务逻辑代码，当前模板仅包含基本的事件监听和通信框架；测试扩展在目标浏览器（Chrome、Edge、Firefox）上的兼容性，不同浏览器对 API 的支持程度可能有差异；移除调试用的 console.log 语句和注释掉的示例代码；仔细检查权限声明是否与实际功能完全匹配，确保没有申请不必要的权限；准备商店上架所需的宣传截图、功能描述和隐私政策文档。工具生成的 manifest.json 结构和脚本文件已经过规范验证，开发者可以在此基础上专注于核心功能的实现。

本工具主要针对基于 Chromium 内核的浏览器进行配置生成，这些浏览器共享相同的扩展规范和 API 体系。包括 Google Chrome、Microsoft Edge、Brave、Vivaldi、Opera 等 Chromium 系浏览器。Manifest V3 格式同样适用于 Firefox 浏览器，但 Firefox 对部分 Chrome 特有 API 的支持程度与 Chrome 有差异（如部分 chrome.* API 在 Firefox 中使用 browser.* 前缀，且部分 API 尚未完全实现）。Safari 浏览器使用独立的 Web Extension 规范，需要通过 Xcode 进行额外适配。工具生成的代码在 Chromium 系浏览器中可直接使用，在 Firefox 中可能需要针对 API 差异进行小幅调整。

Content Script 的 URL 匹配模式（matches 字段）决定了脚本在哪些网页上自动注入执行。匹配模式遵循 Chrome 的 URL 匹配规则：使用通配符 * 匹配任意字符序列，如 https://*.example.com/* 可匹配 example.com 下的所有子页面；可以使用 http/https 协议前缀限制匹配范围；省略路径部分（如 https://www.example.com）仅匹配该域名根路径。常见的配置模式包括：https://*/*（所有 HTTPS 页面）、*://*.example.com/*（指定域名的所有页面）、https://mail.google.com/*（仅匹配特定路径）。避免使用过于宽泛的模式（如 <all_urls>），这会导致脚本在所有页面执行，影响性能且需要额外权限声明。工具提供 URL 匹配模式的输入框，支持多个模式用逗号分隔。

扩展更新后设置丢失通常是由于数据存储方式不当导致的。常见原因包括：将用户设置存储在全局变量中而非 chrome.storage，Service Worker 终止后全局变量会被清除；在 manifest.json 中未声明 storage 权限导致 chrome.storage API 不可用；使用了错误的存储区域（如使用 storage.session 替代 storage.local 或 storage.sync）。正确的做法是在扩展初始化时使用 chrome.storage.local.get 读取之前的设置，使用 chrome.storage.local.set 保存新设置。对于需要跨设备同步的设置（如自定义词库），可以使用 storage.sync，但需注意其容量限制（单个值最大 8KB，总计最大 100KB）。建议在扩展安装时（chrome.runtime.onInstalled 事件）设置默认值，确保更新后原有数据不受影响。