Chrome 扩展开发完全指南 / 第 1 章：Chrome 扩展概述

第 1 章：Chrome 扩展概述

理解 Chrome 扩展的架构原理、核心组件以及从 Manifest V2 到 V3 的演进，是掌握扩展开发的第一步。

1.1 什么是 Chrome 扩展

Chrome 扩展（Chrome Extension）是运行在 Chrome 浏览器中的小型软件程序，用于增强和定制浏览器的功能。与普通网页不同，扩展拥有更高的浏览器 API 访问权限，可以：

• 读取和修改网页内容
• 拦截和修改网络请求
• 管理浏览器标签页和窗口
• 访问书签、历史记录等浏览器数据
• 显示桌面通知
• 在浏览器工具栏添加按钮和 UI

扩展 vs 网页应用 vs 主题

1.2 Chrome 扩展架构

一个 Chrome 扩展由以下核心组件构成：

┌─────────────────────────────────────────────────────┐
│                   Chrome 扩展                        │
│                                                      │
│  ┌──────────────┐   ┌───────────────────────────┐   │
│  │  Manifest     │   │  Service Worker           │   │
│  │  (manifest    │   │  (后台脚本)                │   │
│  │   .json)      │   │  - 事件监听                │   │
│  └──────────────┘   │  - 消息路由                │   │
│                      │  - 数据处理                │   │
│  ┌──────────────┐   └───────────────────────────┘   │
│  │  Content      │                                   │
│  │  Scripts      │   ┌───────────────────────────┐   │
│  │  (内容脚本)   │   │  UI 层                     │   │
│  │  - DOM 操作   │   │  - Popup (弹出页面)        │   │
│  │  - 页面注入   │   │  - Options (选项页面)      │   │
│  └──────────────┘   │  - Side Panel (侧边栏)     │   │
│                      └───────────────────────────┘   │
│  ┌──────────────┐   ┌───────────────────────────┐   │
│  │  Storage      │   │  Permissions              │   │
│  │  (数据存储)   │   │  (权限声明)                │   │
│  └──────────────┘   └───────────────────────────┘   │
└─────────────────────────────────────────────────────┘

各组件职责

1.3 Manifest V2 到 V3 的变化

Manifest V3（MV3）是 Chrome 扩展平台的一次重大升级，于 2020 年提出，2024 年 6 月开始强制淘汰 MV2。

核心变更对比

为什么要迁移到 MV3

1. 安全性提升：禁止远程代码，减少攻击面
2. 性能优化：Service Worker 按需启动，节省内存
3. 隐私保护：声明式网络请求限制了对用户数据的访问
4. 长期支持：Chrome Web Store 已不接受新的 MV2 扩展提交

1.4 Manifest V3 的关键特性

1.4.1 Service Worker 替代 Background Page

MV2 中的 Background Page 是一个持续运行的隐藏页面，而 MV3 的 Service Worker 是事件驱动的：

// MV3 Service Worker (background.js)
// Service Worker 会在事件触发时启动，空闲时终止

// 监听安装事件
chrome.runtime.onInstalled.addListener((details) => {
  console.log('扩展已安装/更新', details.reason);

  // 初始化上下文菜单
  chrome.contextMenus.create({
    id: 'searchSelection',
    title: '搜索 "%s"',
    contexts: ['selection']
  });
});

// 监听来自 Content Script 的消息
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'getData') {
    // 异步处理示例
    fetchData(message.query).then(data => {
      sendResponse({ success: true, data });
    });
    return true; // 保持消息通道开放以等待异步响应
  }
});

// Service Worker 中不可使用
// ❌ window, document, alert, confirm, prompt
// ❌ XMLHttpRequest (需使用 fetch API)
// ❌ 直接操作 DOM

⚠️ 注意：Service Worker 中没有 window 和 document 对象。所有 DOM 操作必须在 Content Script 或 UI 页面（Popup、Options、Side Panel）中完成。

1.4.2 声明式网络请求

// MV2: 使用 webRequest API 拦截和修改请求
chrome.webRequest.onBeforeRequest.addListener(
  (details) => { return { cancel: true }; },
  { urls: ["*://*.ads.example.com/*"] },
  ["blocking"]
);

// MV3: 使用 declarativeNetRequest API 声明规则
// 在 manifest.json 中声明静态规则，或通过 API 动态添加
{
  "declarative_net_request": {
    "rule_resources": [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules.json"
    }]
  }
}

rules.json 规则文件示例：

[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {
      "urlFilter": "||ads.example.com",
      "resourceTypes": ["script", "image", "xmlhttprequest"]
    }
  },
  {
    "id": 2,
    "priority": 1,
    "action": {
      "type": "redirect",
      "redirect": { "url": "https://example.com/replacement.js" }
    },
    "condition": {
      "urlFilter": "||tracker.example.com/tracker.js",
      "resourceTypes": ["script"]
    }
  }
]

1.4.3 统一的 Action API

// MV2: browserAction 和 pageAction 分开使用
chrome.browserAction.setIcon({ path: 'icon-active.png' });
chrome.browserAction.setBadgeText({ text: '5' });

// MV3: 统一为 action API
chrome.action.setIcon({ path: 'icon-active.png' });
chrome.action.setBadgeText({ text: '5' });
chrome.action.setBadgeBackgroundColor({ color: '#FF0000' });

1.5 扩展的运行上下文

Chrome 扩展的代码运行在多个不同的上下文（Context）中，理解这些上下文对于正确编写代码至关重要：

上下文隔离示意

┌──────────────────────┐    ┌──────────────────────┐
│   Extension Context  │    │    Web Page Context   │
│   (扩展上下文)        │    │    (网页上下文)        │
│                      │    │                      │
│  Service Worker      │    │  页面自身的 JavaScript │
│  Popup               │    │  页面全局变量          │
│  Options             │    │  页面 CSS             │
│  Side Panel          │    │                      │
│                      │    │                      │
│  ✅ chrome.* API     │    │  ❌ chrome.* API      │
│  ❌ 页面全局变量      │    │  ✅ 页面全局变量       │
└──────────┬───────────┘    └──────────┬───────────┘
           │                           │
           │    ┌──────────────┐       │
           │    │Content Script│       │
           └────┤ (内容脚本)    ├───────┘
                │              │
                │ 独立的 JS 环境 │
                │ 共享页面 DOM   │
                │ ✅ chrome.*   │
                │ ❌ 页面变量    │
                └──────────────┘

1.6 典型业务场景

场景一：网页内容增强

用户浏览技术文档时，扩展自动在代码块旁添加"一键复制"按钮。

触发: 页面加载完成
组件: Content Script 注入 → 检测 <pre><code> → 添加按钮
交互: 点击按钮 → Content Script 调用 navigator.clipboard.writeText()

场景二：跨站点数据聚合

电商比价工具，在商品页面自动展示其他平台的价格。

触发: 导航到商品页面
组件: Content Script 检测 URL → 通知 Service Worker
处理: Service Worker 调用 API 查询价格 → 返回结果
展示: Content Script 在页面插入比价面板

场景三：浏览器工作流自动化

自动将网页剪藏保存到笔记应用。

触发: 用户右键 → 选择"保存到笔记"
组件: Context Menu → Service Worker → Side Panel
处理: Service Worker 提取页面信息 → 展示在 Side Panel
保存: 用户编辑后 → Service Worker 调用笔记 API

1.7 开发环境准备

1.7.1 安装 Chrome

确保使用 Chrome 116 或更高版本以获得完整 API 支持。

1.7.2 启用开发者模式

1. 打开 Chrome，地址栏输入 chrome://extensions/
2. 开启右上角的 “开发者模式” 开关
3. 你将看到三个按钮：加载已解压的扩展程序、打包扩展程序、更新

1.7.3 推荐开发工具

1.8 扩展阅读

• Chrome 官方扩展开发文档
• Manifest V3 迁移指南
• Chrome 扩展 API 参考
• MV3 已知问题跟踪
• Chromium 扩展论坛