5.2 做一个浏览器插件

目标：了解 Chrome 扩展的基本结构（Manifest V3）、学会在浏览器环境调试，并有一个可以装在自己 Chrome 里的小工具。

浏览器插件是离用户最近的工具之一，可以解决浏览网页时的各种痛点。这个项目将帮你理解浏览器插件的权限模型、事件机制，并掌握前端调试技巧。

🎯 成品要求

插件至少包含 popup（或快捷入口）和一个核心功能
在 chrome://extensions 中加载无报错，可正常运行
有 README 文档说明使用方式与权限申请原因

🧰 准备工作

1. 工具选择

Cursor/Trae + Claude Code：方便生成多文件结构
本地 Chrome 浏览器：用于加载和调试插件

2. 参考资源

官方示例库（强烈推荐）：


git clone https://github.com/GoogleChrome/chrome-extensions-samples

这个仓库包含 100+ 官方示例，遇到不懂的模块可以随时参考。

3. 浏览器配置

打开 Chrome 浏览器
地址栏输入 chrome://extensions
打开右上角的「开发者模式」开关

🛠️ 实践步骤

步骤 1：明确使用场景

先写下具体的痛点和触发方式，这决定了插件的技术架构。

场景示例：

痛点	解决方案	需要的权限
每小时提醒我站立休息	定时弹出通知	`notifications` + `alarms`
在当前标签旁边打开新标签	添加右键菜单或快捷键	`tabs` + `contextMenus`
保存网页中的图片到云端	抓取页面图片 + 上传 API	`activeTab` + `storage`
自动填充常用表单	检测表单并注入数据	`activeTab` + `scripting`

练习用场景（选一个）：

番茄钟提醒器：25 分钟工作 + 5 分钟休息
网页截图工具：截取当前可见区域
快捷笔记：快速保存选中文字到本地

步骤 2：用 Prompt 生成骨架

示例 Prompt（以番茄钟为例）：


请用 Manifest V3 写一个 Chrome 插件，实现以下功能：

## 核心功能
- 番茄钟计时器：25 分钟工作 + 5 分钟休息循环
- 在 popup 中显示当前倒计时
- 时间到后弹出浏览器通知

## 技术结构
- manifest.json：声明权限和文件
- popup.html + popup.js：用户界面，包含开始/暂停/重置按钮
- background.js（service worker）：管理倒计时和通知
- icons/：包含 16x16、48x48、128x128 三种尺寸图标

## 功能细节
- 可在 popup 中自定义工作/休息时长（15/30/60 分钟可选）
- 使用 chrome.alarms API 实现定时器
- 使用 chrome.storage.local 保存配置
- 支持中英文（用 i18n）

请生成完整的文件结构和代码。

让 AI 一次性生成所有文件，包括 manifest、popup、background 脚本与本地存储逻辑。

步骤 3：本地加载调试

3.1 加载插件

打开 chrome://extensions
确认「开发者模式」已开启
点击「加载已解压的扩展程序」
选择你的插件文件夹

3.2 固定到工具栏

点击 Chrome 工具栏右侧的拼图图标
找到你的插件，点击📌固定
现在可以直接点击图标打开 popup

3.3 查看日志

Popup 日志：

右键点击 popup 图标 → 检查（或「审查元素」）
打开 DevTools Console 查看 console.log 输出

Background Service Worker 日志：

在 chrome://extensions 找到你的插件
点击「service worker」链接
会弹出 DevTools 窗口，查看后台脚本日志

步骤 4：快速排错

问题类型	症状	排查方法	解决方案
权限不足	报错 `Cannot access ...`	检查 manifest.json `permissions` 字段	添加所需权限（如 `tabs`、`storage`、`notifications`）
Service Worker 被回收	定时器停止工作	后台脚本没有持久化状态	使用 `chrome.alarms` 替代 `setTimeout`；监听 `chrome.runtime.onInstalled` 和 `onStartup`
无法操作页面 DOM	popup 中 `document.querySelector` 找不到元素	popup 和网页是两个独立的 DOM	通过 `chrome.scripting.executeScript` 注入 content script
manifest 报错	插件加载失败	查看 `chrome://extensions` 的错误提示	修复 JSON 格式、检查文件路径、确认 manifest_version 是 3
图标不显示	工具栏显示默认图标	icons 路径错误或文件缺失	确保 `icons` 字段指向正确的文件路径
数据丢失	刷新后配置消失	数据存在内存变量中	使用 `chrome.storage.local.set/get` 持久化

调试技巧：


// 在 background.js 中添加详细日志
chrome.runtime.onInstalled.addListener(() => {
  console.log('插件已安装');
});
 
chrome.alarms.onAlarm.addListener((alarm) => {
  console.log('闹钟触发:', alarm.name);
});
 
// 在 popup.js 中调试存储
chrome.storage.local.get(null, (data) => {
  console.log('当前存储的所有数据:', data);
});

步骤 5：打包与分享

方式一：本地使用（最简单）

直接在 chrome://extensions 加载即可，无需打包。

方式二：分享给朋友

将插件文件夹打包成 .zip 文件
朋友解压后在自己的 Chrome 中加载
注意：未上架的插件每次 Chrome 重启会有安全提示

方式三：上架到 Chrome Web Store（可选）

准备素材：

128x128 图标（必需）
至少 1 张 1280x800 或 640x400 的截图
详细描述（功能、使用方法、隐私说明）
分类标签

上架步骤：

访问 Chrome Web Store Developer Console
支付一次性注册费（$5）
点击「新建项目」，上传 .zip 文件
填写商店信息：
- 标题、简短描述、详细描述
- 上传截图和宣传图
- 选择类别和语言
- 隐私说明：必须说明为什么需要每个权限
提交审核（通常 1-3 个工作日）

审核常见拒绝原因：

权限申请过多但未说明原因
功能描述不清晰
截图质量太低或无法体现功能
违反内容政策（广告、抄袭等）

✅ 质量检查

功能测试

Popup 界面能正常打开和关闭
核心功能在多个标签页都能正常工作
浏览器重启后配置不丢失

兼容性测试

在 Chrome、Edge（Chromium 内核）都能正常运行
Popup 界面适配暗色/浅色模式
不同屏幕分辨率下界面不错位

安全与隐私

只申请必要的最小权限
在 README 中明确说明每个权限的用途
敏感数据（如 API Key）不硬编码在代码中

文档完整性

README 包含安装步骤
有使用截图或动图演示
说明如何反馈问题

🔁 进阶练习

练习 1：同步数据到云端

将配置从 chrome.storage.local 改为 chrome.storage.sync
登录 Chrome 后配置会自动同步到其他设备
适合多设备使用的插件

练习 2：增加多入口交互

右键菜单：


// background.js
chrome.runtime.onInstalled.addListener(() => {
  chrome.contextMenus.create({
    id: 'saveText',
    title: '保存选中文字',
    contexts: ['selection']
  });
});
 
chrome.contextMenus.onClicked.addListener((info, tab) => {
  console.log('选中的文字:', info.selectionText);
});

快捷键：


// manifest.json
{
  "commands": {
    "_execute_action": {
      "suggested_key": {
        "default": "Ctrl+Shift+P"
      }
    },
    "toggle-timer": {
      "suggested_key": {
        "default": "Ctrl+Shift+T"
      },
      "description": "切换计时器"
    }
  }
}

Omnibox（地址栏交互）：


// manifest.json
{
  "omnibox": { "keyword": "pm" }
}


// background.js
chrome.omnibox.onInputEntered.addListener((text) => {
  console.log('用户输入:', text);
  // 创建新的番茄钟
});

练习 3：为插件做 Landing Page

结合 5.1 简单网站和 5.5 SEO 网站
搭建一个介绍插件功能的页面
收集用户邮箱，发布更新时通知
添加反馈表单，收集使用建议

💡 常见问题

Q：为什么我的定时器在浏览器最小化后就停了？ A：不要用 setTimeout/setInterval，改用 chrome.alarms API。Service Worker 会被浏览器自动回收，只有 alarms 能保证持续触发。

Q：如何在网页中注入按钮或修改样式？ A：使用 Content Script。在 manifest.json 中配置：


{
  "content_scripts": [{
    "matches": ["https://*.example.com/*"],
    "js": ["content.js"],
    "css": ["content.css"]
  }]
}

Q：插件报错 “Extensions cannot be loaded…” A：检查是否有文件权限问题，或文件夹路径中有中文/特殊字符。

Q：如何调试 Content Script？ A：打开网页，按 F12 打开 DevTools，在 Console 中可以看到 content script 的日志。

🎯 本节小结

完成这个项目后，你应该掌握了：

✅ Chrome 扩展的基本架构（Manifest V3） ✅ 如何使用 popup、background、content script ✅ 如何在浏览器中调试扩展程序 ✅ 常见权限和 API 的使用方法

**把插件分享给朋友试用，收集真实反馈！**接下来进入 5.3 爬虫，学习如何抓取和处理网页数据。