Chrome 扩展开发指南：从入门到精通 Manifest V3Chrome 扩展开发完全指南：从入门到精通 Manif

本文基于 Manifest V3 标准，系统性地介绍 Chrome 浏览器扩展开发的核心知识，涵盖项目架构、核心组件、消息通信、存储方案、网络请求、安全实践、现代工具链集成等内容，并提供大量可运行的代码示例。

前言

Chrome 扩展是一种能够扩展浏览器功能的小型程序。它可以修改网页内容、添加新功能、与 Web 服务交互，甚至构建完整的应用程序。随着 Manifest V3 的全面推行，扩展开发迎来了重大变革：Background Pages 被 Service Workers 取代，网络请求拦截改用 declarativeNetRequest，安全策略更加严格。

特性	Manifest V2	Manifest V3
后台脚本	Background Pages	Service Workers
远程代码	允许	禁止
eval()	允许	禁止
网络请求拦截	webRequest (blocking)	declarativeNetRequest
内容安全策略	较宽松	更严格
Host Permissions	在 permissions 中	单独的 host_permissions
Promise 支持	部分支持	全面支持

本文将带你全面掌握现代 Chrome 扩展开发。

一、快速开始

1.1 最小可运行扩展

一个 Chrome 扩展至少需要一个 manifest.json 文件：

{
  "manifest_version": 3,
  "name": "我的第一个扩展",
  "version": "1.0.0",
  "description": "一个简单的 Chrome 扩展示例",
  "action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "icons/icon16.png",
      "48": "icons/icon48.png",
      "128": "icons/icon128.png"
    }
  }
}

创建 popup.html：

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <style>
    body { width: 200px; padding: 16px; font-family: system-ui; }
    h1 { font-size: 16px; margin: 0; }
  </style>
</head>
<body>
  <h1>👋 Hello Extension!</h1>
</body>
</html>

1.2 加载扩展

打开 chrome://extensions/
启用右上角的"开发者模式"
点击"加载已解压的扩展程序"
选择项目目录

二、项目结构

2.1 标准项目结构

my-extension/
├── manifest.json          # 扩展清单（必需）
├── background.js          # Service Worker（后台脚本）
├── content-script.js      # 内容脚本（注入网页）
├── popup.html/js/css      # 弹出页面
├── sidebar.html/js/css    # 侧边栏（Side Panel）
├── options.html/js/css    # 设置页面
├── icons/                 # 图标
│   ├── icon16.png
│   ├── icon48.png
│   └── icon128.png
├── _locales/              # 国际化
│   ├── en/messages.json
│   └── zh_CN/messages.json
└── lib/                   # 第三方库

2.2 架构概览图

┌───────────────────────────────────────────────────────────────────────────┐
│                            浏览器扩展架构图                                  │
├───────────────────────────────────────────────────────────────────────────┤
│                                                                           │
│  ┌─────────────────┐    消息通信      ┌─────────────────┐                  │
│  │   Web Page      │◄──────────────► │  Content Script │                  │
│  │   (网页)        │   postMessage   │    (内容脚本)     │                  │
│  └─────────────────┘                 └────────┬────────┘                  │
│                                               │                           │
│                                    chrome.runtime.sendMessage             │
│                                               │                           │
│                                               ▼                           │
│  ┌─────────────────────────────────────────────────────────────────┐      │
│  │                    Background Service Worker                    │      │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐         │      │
│  │  │  消息路由 │   │ API 调用 │  │  状态管理 │  │  定时任务 │          │      │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘         │      │
│  └─────────────────────────────────────────────────────────────────┘      │
│           │                    │                    │                     │
│           ▼                    ▼                    ▼                     │
│  ┌─────────────┐      ┌─────────────┐      ┌─────────────┐                │
│  │   Popup     │      │  Side Panel │      │   Options   │                │
│  │   (弹窗)     │      │  (侧边栏)    │      │   (设置页)  │                 │
│  └─────────────┘      └─────────────┘      └─────────────┘                │
│                                                                           │
│  ┌─────────────────────────────────────────────────────────────────┐      │
│  │                        存储层 (Storage Layer)                    │      │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐ │      │
│  │  │   Local    │  │    Sync    │  │  Session   │  │  IndexedDB │ │      │
│  │  │  Storage   │  │  Storage   │  │  Storage   │  │            │ │      │
│  │  └────────────┘  └────────────┘  └────────────┘  └────────────┘ │      │
│  └─────────────────────────────────────────────────────────────────┘      │
└───────────────────────────────────────────────────────────────────────────┘

2.3 各文件职责

文件	职责	运行环境
manifest.json	扩展配置和元数据	-
background.js	后台任务、事件监听、API调用	Service Worker
content-script.js	与网页交互、DOM操作	网页上下文
sidebar.js/popup.js	用户界面逻辑	扩展页面上下文

三、Manifest 配置详解

3.1 完整配置示例

{
  "manifest_version": 3,
  "name": "__MSG_extName__",
  "version": "1.0.0",
  "description": "__MSG_extDescription__",
  "default_locale": "zh_CN",

  "icons": {
    "16": "icons/icon16.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },

  "permissions": [
    "storage",
    "tabs",
    "activeTab",
    "scripting",
    "sidePanel",
    "contextMenus",
    "alarms",
    "notifications"
  ],

  "optional_permissions": ["history", "bookmarks"],

  "host_permissions": [
    "https://*.example.com/*",
    "https://api.openai.com/*"
  ],

  "background": {
    "service_worker": "background.js",
    "type": "module"
  },

  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["content-script.js"],
      "css": ["content-style.css"],
      "run_at": "document_idle"
    }
  ],

  "side_panel": {
    "default_path": "sidebar.html"
  },

  "action": {
    "default_popup": "popup.html",
    "default_icon": { "16": "icons/icon16.png", "48": "icons/icon48.png" },
    "default_title": "点击打开"
  },

  "options_ui": {
    "page": "options.html",
    "open_in_tab": false
  },

  "commands": {
    "toggle-sidebar": {
      "suggested_key": { "default": "Ctrl+Shift+S", "mac": "Command+Shift+S" },
      "description": "切换侧边栏"
    }
  },

  "web_accessible_resources": [
    { "resources": ["images/*"], "matches": ["<all_urls>"] }
  ],

  "externally_connectable": {
    "matches": ["http://localhost:*/*", "https://*.yourdomain.com/*"]
  }
}

3.2 关键字段说明

permissions vs host_permissions

// API 权限 - 访问 Chrome API
"permissions": [
  "tabs",          // 访问标签页信息
  "storage",       // 本地存储
  "sidePanel",     // 侧边栏功能
  "activeTab",     // 当前活动标签页
  "scripting",     // 动态注入脚本
  "notifications", // 桌面通知
  "contextMenus",  // 右键菜单
  "alarms"         // 定时器
],

// 主机权限 - 访问指定网站
"host_permissions": [
  "<all_urls>",                  // 所有网站
  "https://*.google.com/*",      // 特定域名
  "http://localhost:*/*"         // 本地开发
]

run_at 取值说明

document_start: DOM 开始构建时注入
document_end: DOM 构建完成时注入（DOMContentLoaded 之前）
document_idle: DOMContentLoaded 之后注入（默认，推荐）

3.3 常用权限速查表

权限	用途
`storage`	本地存储
`tabs`	标签页管理
`activeTab`	临时访问当前标签页
`scripting`	动态注入脚本
`sidePanel`	侧边栏功能
`contextMenus`	右键菜单
`alarms`	定时器
`notifications`	系统通知
`cookies`	Cookie 管理
`history`	浏览历史
`bookmarks`	书签管理
`downloads`	下载管理
`offscreen`	离屏文档
`declarativeNetRequest`	网络请求拦截

四、核心组件详解

4.1 Background Service Worker

Service Worker 是扩展的"大脑"，负责事件监听、状态管理和跨组件通信。

// background.js

// ============ 生命周期事件 ============
chrome.runtime.onInstalled.addListener(async (details) => {
  console.log('扩展已安装/更新:', details.reason)

  if (details.reason === 'install') {
    // 首次安装：初始化存储
    await chrome.storage.local.set({
      settings: { theme: 'light', enabled: true }
    })

    // 创建右键菜单
    chrome.contextMenus.create({
      id: 'main-menu',
      title: '使用扩展处理',
      contexts: ['selection', 'page']
    })
  }
})

// ============ 消息处理中心 ============
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  handleMessage(message, sender)
    .then(sendResponse)
    .catch(err => sendResponse({ error: err.message }))
  return true // 异步响应必须返回 true
})

async function handleMessage(message, sender) {
  switch (message.action) {
    case 'getData':
      return chrome.storage.local.get(message.key)
    case 'setData':
      await chrome.storage.local.set({ [message.key]: message.value })
      return { success: true }
    case 'openSidebar':
      await chrome.sidePanel.open({ tabId: sender.tab.id })
      return { success: true }
    default:
      throw new Error(`未知操作: ${message.action}`)
  }
}

// ============ 定时任务 ============
chrome.alarms.create('keepAlive', { periodInMinutes: 0.5 })
chrome.alarms.onAlarm.addListener((alarm) => {
  if (alarm.name === 'keepAlive') {
    console.log('Service Worker 保持活跃')
  }
})

// ============ 快捷键 ============
chrome.commands.onCommand.addListener(async (command) => {
  if (command === 'toggle-sidebar') {
    const [tab] = await chrome.tabs.query({ active: true, currentWindow: true })
    if (tab) await chrome.sidePanel.open({ tabId: tab.id })
  }
})

// ============ 侧边栏配置 ============
chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true })

console.log('Background Service Worker 已启动')

4.2 Content Script

Content Script 注入到网页中运行，可以访问和操作 DOM。

// content-script.js
;(function() {
  'use strict'

  // 防止重复注入
  if (window.__EXTENSION_LOADED__) return
  window.__EXTENSION_LOADED__ = true

  console.log('[扩展] Content Script 已注入:', location.href)

  // 发送消息到 Background
  async function sendMessage(action, data = {}) {
    return new Promise((resolve, reject) => {
      chrome.runtime.sendMessage({ action, ...data }, (response) => {
        if (chrome.runtime.lastError) {
          reject(new Error(chrome.runtime.lastError.message))
        } else if (response?.error) {
          reject(new Error(response.error))
        } else {
          resolve(response)
        }
      })
    })
  }

  // 接收来自 Background 的消息
  chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
    switch (message.action) {
      case 'getPageInfo':
        sendResponse({
          url: location.href,
          title: document.title,
          content: document.body.innerText.slice(0, 5000)
        })
        break
      case 'highlight':
        highlightText(message.text)
        sendResponse({ success: true })
        break
    }
    return false
  })

  // 高亮文本
  function highlightText(text) {
    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT)
    while (walker.nextNode()) {
      const node = walker.currentNode
      if (node.textContent.includes(text)) {
        const mark = document.createElement('mark')
        mark.style.cssText = 'background: yellow; padding: 2px 4px;'
        mark.textContent = node.textContent
        node.parentNode.replaceChild(mark, node)
      }
    }
  }

  // 与网页通信（可选）
  window.addEventListener('message', async (event) => {
    if (event.source !== window || event.data?.type !== 'FROM_PAGE') return
    try {
      const response = await sendMessage(event.data.action, event.data.payload)
      window.postMessage({ type: 'FROM_EXTENSION', response }, '*')
    } catch (error) {
      window.postMessage({ type: 'FROM_EXTENSION', error: error.message }, '*')
    }
  })
})()

4.3 Side Panel（侧边栏）

<!-- sidebar.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    body { font-family: system-ui; background: #f5f5f5; }
    .container { height: 100vh; display: flex; flex-direction: column; }
    .header { padding: 16px; background: #4285f4; color: white; }
    .content { flex: 1; padding: 16px; overflow-y: auto; }
    .message { padding: 12px; margin: 8px 0; background: white; border-radius: 8px; }
    .message.user { background: #e3f2fd; margin-left: 20%; }
    .input-area { padding: 16px; border-top: 1px solid #ddd; background: white; }
    textarea { width: 100%; padding: 10px; border: 1px solid #ddd; border-radius: 8px; resize: none; }
    button { margin-top: 8px; width: 100%; padding: 10px; background: #4285f4; color: white; border: none; border-radius: 8px; cursor: pointer; }
    button:hover { background: #3367d6; }
    button:disabled { background: #ccc; }
  </style>
</head>
<body>
  <div class="container">
    <header class="header"><h1>🚀 我的扩展</h1></header>
    <main class="content" id="messages"></main>
    <div class="input-area">
      <textarea id="input" rows="3" placeholder="输入内容... (Ctrl+Enter 发送)"></textarea>
      <button id="send">发送</button>
    </div>
  </div>
  <script src="sidebar.js"></script>
</body>
</html>

// sidebar.js
document.addEventListener('DOMContentLoaded', () => {
  const input = document.getElementById('input')
  const sendBtn = document.getElementById('send')
  const messagesContainer = document.getElementById('messages')

  function appendMessage(content, type = 'user') {
    const div = document.createElement('div')
    div.className = `message ${type}`
    div.textContent = content
    messagesContainer.appendChild(div)
    messagesContainer.scrollTop = messagesContainer.scrollHeight
  }

  async function handleSend() {
    const text = input.value.trim()
    if (!text) return

    appendMessage(text, 'user')
    input.value = ''
    sendBtn.disabled = true

    try {
      const response = await chrome.runtime.sendMessage({ action: 'process', text })
      appendMessage(response.result || '处理完成', 'assistant')
    } catch (error) {
      appendMessage('错误: ' + error.message, 'error')
    } finally {
      sendBtn.disabled = false
    }
  }

  sendBtn.addEventListener('click', handleSend)
  input.addEventListener('keydown', (e) => {
    if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) handleSend()
  })
})

五、消息通信机制

5.1 通信架构图

┌──────────┐    postMessage    ┌──────────────┐   chrome.runtime   ┌──────────────┐
│ Web Page │ ◄──────────────►  │Content Script│ ◄────────────────► │  Background  │
└──────────┘                   └──────────────┘                    └──────────────┘
                                      ▲                                  ▲
                                      │     chrome.runtime.sendMessage   │
                                      ▼                                  │
                               ┌──────────────┐                          │
                               │ Popup/Sidebar│ ◄────────────────────────┘
                               └──────────────┘     chrome.tabs.sendMessage

5.2 消息发送模式

// 1. Content Script / Popup / Sidebar → Background
chrome.runtime.sendMessage({ action: 'getData', key: 'settings' }, (response) => {
  if (chrome.runtime.lastError) {
    console.error('发送失败:', chrome.runtime.lastError.message)
    return
  }
  console.log('响应:', response)
})

// 2. Background → Content Script（需要指定 tabId）
async function sendToActiveTab(message) {
  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true })
  return chrome.tabs.sendMessage(tab.id, message)
}

// 3. 网页 ↔ Content Script（使用 postMessage）
// 网页端
window.postMessage({ type: 'FROM_PAGE', action: 'getData' }, '*')

// Content Script 端
window.addEventListener('message', (event) => {
  if (event.source !== window || event.data.type !== 'FROM_PAGE') return
  window.postMessage({ type: 'FROM_EXTENSION', data: {} }, '*')
})

5.3 长连接（Port）

// 建立连接
const port = chrome.runtime.connect({ name: 'sidebar' })

port.onMessage.addListener((message) => {
  console.log('收到:', message)
})

port.postMessage({ type: 'subscribe', channel: 'updates' })

// Background 端监听
const connections = new Map()

chrome.runtime.onConnect.addListener((port) => {
  connections.set(port.name, port)

  port.onMessage.addListener((message) => {
    port.postMessage({ type: 'ack', id: message.id })
  })

  port.onDisconnect.addListener(() => {
    connections.delete(port.name)
  })
})

六、数据存储

6.1 chrome.storage API

// 本地存储（无大小限制，不同步）
await chrome.storage.local.set({ key: 'value', settings: { theme: 'dark' } })
const { key, settings } = await chrome.storage.local.get(['key', 'settings'])

// 同步存储（跟随用户账号，限制 100KB）
await chrome.storage.sync.set({ preferences: { fontSize: 14 } })

// 会话存储（扩展关闭后清除）
await chrome.storage.session.set({ tempData: 'xxx' })

// 监听存储变化
chrome.storage.onChanged.addListener((changes, areaName) => {
  for (const [key, { oldValue, newValue }] of Object.entries(changes)) {
    console.log(`[${areaName}] ${key}: ${oldValue} → ${newValue}`)
  }
})

6.2 封装存储工具类

class Storage {
  constructor(area = 'local') {
    this.storage = chrome.storage[area]
    this.cache = new Map()
  }

  async get(key, defaultValue = null) {
    if (this.cache.has(key)) return this.cache.get(key)
    const result = await this.storage.get(key)
    const value = result[key] ?? defaultValue
    this.cache.set(key, value)
    return value
  }

  async set(key, value) {
    await this.storage.set({ [key]: value })
    this.cache.set(key, value)
  }

  async remove(key) {
    await this.storage.remove(key)
    this.cache.delete(key)
  }
}

const storage = new Storage('local')
await storage.set('user', { name: 'John' })
const user = await storage.get('user')

七、网络请求

7.1 HTTP 请求封装

class HttpClient {
  constructor(baseURL = '', defaultHeaders = {}) {
    this.baseURL = baseURL
    this.defaultHeaders = { 'Content-Type': 'application/json', ...defaultHeaders }
  }

  async request(endpoint, options = {}) {
    const response = await fetch(this.baseURL + endpoint, {
      method: options.method || 'GET',
      headers: { ...this.defaultHeaders, ...options.headers },
      body: options.body ? JSON.stringify(options.body) : undefined
    })

    const data = await response.json()
    if (!response.ok) throw new Error(data.message || `HTTP ${response.status}`)
    return data
  }

  get(endpoint) { return this.request(endpoint) }
  post(endpoint, body) { return this.request(endpoint, { method: 'POST', body }) }
}

const api = new HttpClient('https://api.example.com')
const data = await api.get('/users')

7.2 流式 AI 对话

class AIStreamClient {
  constructor(apiKey, provider = 'openai') {
    this.apiKey = apiKey
    this.provider = provider
  }

  async chat(messages, onChunk, onComplete) {
    const isAnthropic = this.provider === 'anthropic'
    const url = isAnthropic
      ? 'https://api.anthropic.com/v1/messages'
      : 'https://api.openai.com/v1/chat/completions'

    const headers = {
      'Content-Type': 'application/json',
      ...(isAnthropic
        ? { 'x-api-key': this.apiKey, 'anthropic-version': '2023-06-01' }
        : { 'Authorization': `Bearer ${this.apiKey}` })
    }

    const response = await fetch(url, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        model: isAnthropic ? 'claude-3-sonnet-20240229' : 'gpt-4',
        messages,
        stream: true,
        max_tokens: 4096
      })
    })

    const reader = response.body.getReader()
    const decoder = new TextDecoder()
    let fullContent = ''

    while (true) {
      const { done, value } = await reader.read()
      if (done) break

      const lines = decoder.decode(value).split('\n')
      for (const line of lines) {
        if (!line.startsWith('data: ') || line.includes('[DONE]')) continue
        try {
          const json = JSON.parse(line.slice(6))
          const content = isAnthropic
            ? json.delta?.text
            : json.choices?.[0]?.delta?.content
          if (content) {
            fullContent += content
            onChunk?.(content, fullContent)
          }
        } catch {}
      }
    }

    onComplete?.(fullContent)
    return fullContent
  }
}

八、安全最佳实践

8.1 输入验证与净化

class SecurityUtils {
  // HTML 转义 - 防止 XSS
  static escapeHtml(str) {
    const map = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#x27;' }
    return String(str).replace(/[&<>"']/g, c => map[c])
  }

  // 验证 URL
  static isValidUrl(string) {
    try {
      const url = new URL(string)
      return ['http:', 'https:'].includes(url.protocol)
    } catch { return false }
  }

  // 安全 JSON 解析
  static safeJsonParse(str, defaultValue = null) {
    try { return JSON.parse(str) } catch { return defaultValue }
  }
}

8.2 加密存储

class SecureStorage {
  constructor() {
    this.encryptionKey = null
  }

  async init() {
    if (this.encryptionKey) return
    const result = await chrome.storage.local.get('encryption

Key')
    if (result.encryptionKey) {
      const keyData = new Uint8Array(result.encryptionKey)
      this.encryptionKey = await crypto.subtle.importKey(
        'raw', keyData, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']
      )
    } else {
      this.encryptionKey = await crypto.subtle.generateKey(
        { name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt']
      )
      const exported = await crypto.subtle.exportKey('raw', this.encryptionKey)
      await chrome.storage.local.set({ encryptionKey: Array.from(new Uint8Array(exported)) })
    }
  }

  async encrypt(data) {
    const iv = crypto.getRandomValues(new Uint8Array(12))
    const encoded = new TextEncoder().encode(JSON.stringify(data))
    const encrypted = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, this.encryptionKey, encoded)
    return { iv: Array.from(iv), data: Array.from(new Uint8Array(encrypted)) }
  }

  async decrypt(encryptedData) {
    const iv = new Uint8Array(encryptedData.iv)
    const data = new Uint8Array(encryptedData.data)
    const decrypted = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, this.encryptionKey, data)
    return JSON.parse(new TextDecoder().decode(decrypted))
  }

  async setSecure(key, value) {
    await this.init()
    const encrypted = await this.encrypt(value)
    await chrome.storage.local.set({ [key]: encrypted })
  }

  async getSecure(key) {
    await this.init()
    const result = await chrome.storage.local.get(key)
    if (!result[key]) return null
    return this.decrypt(result[key])
  }
}

// 使用示例
const secureStorage = new SecureStorage()
await secureStorage.setSecure('apiKey', 'sk-secret-key')
const apiKey = await secureStorage.getSecure('apiKey')

8.3 权限最小化原则

{
  "permissions": [
    "storage",    // 必需：数据存储
    "activeTab"   // 必需：获取当前页面信息
  ],
  "optional_permissions": [
    "tabs",       // 可选：需要时再请求
    "history"     // 可选：需要时再请求
  ],
  "host_permissions": [
    "https://api.example.com/*"  // 只允许访问必要的 API
  ]
}

九、高级 Chrome API

9.1 declarativeNetRequest API

声明式网络请求拦截，替代 Manifest V2 的 webRequest：

// manifest.json
{
  "permissions": ["declarativeNetRequest"],
  "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"]
    }
  },
  {
    "id": 2,
    "priority": 2,
    "action": {
      "type": "modifyHeaders",
      "requestHeaders": [{ "header": "X-Custom", "operation": "set", "value": "value" }]
    },
    "condition": { "urlFilter": "*://api.example.com/*", "resourceTypes": ["xmlhttprequest"] }
  }
]

// 动态添加规则
async function addBlockRule(domain) {
  const rules = await chrome.declarativeNetRequest.getDynamicRules()
  const nextId = Math.max(0, ...rules.map(r => r.id)) + 1

  await chrome.declarativeNetRequest.updateDynamicRules({
    addRules: [{
      id: nextId,
      priority: 1,
      action: { type: 'block' },
      condition: { urlFilter: `*://${domain}/*`, resourceTypes: ['script'] }
    }]
  })
}

9.2 Offscreen Documents

在 Manifest V3 中创建隐藏的 DOM 环境：

// manifest.json
{ "permissions": ["offscreen"] }

// background.js
async function createOffscreenDocument() {
  const contexts = await chrome.runtime.getContexts({ contextTypes: ['OFFSCREEN_DOCUMENT'] })
  if (contexts.length > 0) return

  await chrome.offscreen.createDocument({
    url: 'offscreen.html',
    reasons: ['DOM_PARSER', 'CLIPBOARD'],
    justification: '需要解析 HTML 和操作剪贴板'
  })
}

// offscreen.js
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.target !== 'offscreen') return

  if (message.action === 'parseHTML') {
    const parser = new DOMParser()
    const doc = parser.parseFromString(message.html, 'text/html')
    sendResponse({ title: doc.title, headings: [...doc.querySelectorAll('h1,h2')].map(h => h.textContent) })
  }

  if (message.action === 'copyToClipboard') {
    navigator.clipboard.writeText(message.text).then(() => sendResponse({ success: true }))
    return true
  }
})

十、国际化支持

10.1 配置国际化

// manifest.json
{ "default_locale": "zh_CN" }

// _locales/zh_CN/messages.json
{
  "extName": { "message": "我的扩展", "description": "扩展名称" },
  "extDescription": { "message": "一个强大的浏览器扩展", "description": "扩展描述" },
  "buttonSend": { "message": "发送", "description": "发送按钮文本" },
  "greeting": { "message": "你好，$USER$！", "placeholders": { "user": { "content": "$1", "example": "张三" } } }
}

// _locales/en/messages.json
{
  "extName": { "message": "My Extension" },
  "extDescription": { "message": "A powerful browser extension" },
  "buttonSend": { "message": "Send" },
  "greeting": { "message": "Hello, $USER$!", "placeholders": { "user": { "content": "$1" } } }
}

10.2 使用国际化

// 获取翻译
const name = chrome.i18n.getMessage('extName')
const greeting = chrome.i18n.getMessage('greeting', ['张三'])

// 获取语言
const uiLanguage = chrome.i18n.getUILanguage() // "zh-CN"

// HTML 中使用（需要手动替换）
document.querySelectorAll('[data-i18n]').forEach(el => {
  el.textContent = chrome.i18n.getMessage(el.dataset.i18n)
})

<!-- HTML 使用 -->
<button data-i18n="buttonSend">Send</button>

<!-- CSS 使用（manifest.json 中的字段） -->
<!-- "__MSG_extName__" 会被自动替换 -->

十一、现代开发工具链

11.1 Vite + CRXJS

npm create vite@latest my-extension -- --template react-ts
cd my-extension
npm install @crxjs/vite-plugin -D

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { crx } from '@crxjs/vite-plugin'
import manifest from './manifest.json'

export default defineConfig({
  plugins: [react(), crx({ manifest })]
})

11.2 TypeScript 配置

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["chrome"]
  }
}

npm install @types/chrome -D

十二、UI 框架集成

12.1 React 集成

// src/popup/App.tsx
import { useState, useEffect } from 'react'

export default function App() {
  const [settings, setSettings] = useState({ theme: 'light', enabled: true })

  useEffect(() => {
    chrome.storage.sync.get(['settings'], (result) => {
      if (result.settings) setSettings(result.settings)
    })
  }, [])

  const updateSettings = async (updates: Partial<typeof settings>) => {
    const newSettings = { ...settings, ...updates }
    setSettings(newSettings)
    await chrome.storage.sync.set({ settings: newSettings })
  }

  return (
    <div className={`app ${settings.theme}`}>
      <h1>扩展设置</h1>
      <label>
        <input
          type="checkbox"
          checked={settings.enabled}
          onChange={(e) => updateSettings({ enabled: e.target.checked })}
        />
        启用扩展
      </label>
    </div>
  )
}

12.2 Vue 3 集成

<!-- src/popup/App.vue -->
<template>
  <div :class="['app', settings.theme]">
    <h1>扩展设置</h1>
    <label>
      <input type="checkbox" v-model="settings.enabled" @change="saveSettings" />
      启用扩展
    </label>
  </div>
</template>

<script setup lang="ts">
import { reactive, onMounted } from 'vue'

const settings = reactive({ enabled: true, theme: 'light' })

onMounted(async () => {
  const result = await chrome.storage.sync.get(['settings'])
  if (result.settings) Object.assign(settings, result.settings)
})

async function saveSettings() {
  await chrome.storage.sync.set({ settings: { ...settings } })
}
</script>

12.3 Vue Composables

// src/composables/useStorage.ts
import { ref, watch, onMounted } from 'vue'

export function useStorage<T>(key: string, defaultValue: T) {
  const data = ref<T>(defaultValue)
  const loading = ref(true)

  onMounted(async () => {
    const result = await chrome.storage.local.get(key)
    if (result[key] !== undefined) data.value = result[key]
    loading.value = false
  })

  watch(data, async (newValue) => {
    await chrome.storage.local.set({ [key]: newValue })
  }, { deep: true })

  chrome.storage.onChanged.addListener((changes, area) => {
    if (area === 'local' && changes[key]) data.value = changes[key].newValue
  })

  return { data, loading }
}

// 使用
// const { data: settings } = useStorage('settings', { theme: 'light' })

十三、调试技巧

13.1 调试各组件

组件	调试方法
Background	`chrome://extensions/` → 点击 "Service Worker" 链接
Content Script	目标网页 → F12 → Console/Sources
Popup	右键扩展图标 → 检查弹出内容
Side Panel	侧边栏内 → 右键 → 检查

13.2 常用调试代码

// 查看扩展信息
console.log(chrome.runtime.getManifest())

// 查看所有存储数据
chrome.storage.local.get(null, console.log)
chrome.storage.sync.get(null, console.log)

// 查看当前标签页
chrome.tabs.query({ active: true, currentWindow: true }, console.log)

// 检查权限
chrome.permissions.getAll(console.log)

13.3 Service Worker 问题排查

// 保持 Service Worker 活跃
chrome.alarms.create('keepAlive', { periodInMinutes: 0.5 })

chrome.alarms.onAlarm.addListener((alarm) => {
  if (alarm.name === 'keepAlive') console.log('Service Worker 保持活跃')
})

// 不要使用全局变量存储状态！
// ❌ 错误
let cachedData = {}

// ✅ 正确：使用 chrome.storage
async function getData(key) {
  const result = await chrome.storage.local.get(key)
  return result[key]
}

十四、发布与更新

14.1 准备工作

注册开发者账号（一次性费用 $5）
准备素材：
- 128x128 图标
- 1280x800 或 640x400 截图（1-5 张）
- 440x280 宣传图（可选）
- 详细描述和隐私政策

14.2 打包扩展

cd dist
zip -r ../extension.zip . -x "*.git*" -x "node_modules/*"

14.3 发布流程

访问 Chrome Web Store Developer Dashboard
点击"新建商品"
上传 ZIP 文件
填写商品详情
提交审核（通常 1-3 天）

十五、监控与分析

15.1 错误追踪

/**
 * 错误追踪系统
 */
class ErrorTracker {
  constructor(options = {}) {
    this.endpoint = options.endpoint
    this.maxErrors = options.maxErrors || 100
    this.errors = []
    this.setupGlobalHandlers()
  }

  setupGlobalHandlers() {
    // 捕获未处理的错误
    self.addEventListener('error', (event) => {
      this.capture({
        type: 'uncaught_error',
        message: event.message,
        filename: event.filename,
        lineno: event.lineno,
        stack: event.error?.stack
      })
    })

    // 捕获未处理的 Promise 拒绝
    self.addEventListener('unhandledrejection', (event) => {
      this.capture({
        type: 'unhandled_rejection',
        reason: event.reason?.message || String(event.reason),
        stack: event.reason?.stack
      })
    })
  }

  capture(errorInfo) {
    const error = {
      ...errorInfo,
      timestamp: Date.now(),
      url: location.href,
      userAgent: navigator.userAgent,
      extensionVersion: chrome.runtime.getManifest().version
    }

    this.errors.push(error)
    if (this.errors.length > this.maxErrors) this.errors.shift()

    this.saveToStorage()
    if (this.endpoint) this.sendToServer(error)
    console.error('[ErrorTracker]', error)
  }

  async saveToStorage() {
    await chrome.storage.local.set({ errorLogs: this.errors })
  }

  async sendToServer(error) {
    try {
      await fetch(this.endpoint, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(error)
      })
    } catch (e) {
      console.warn('发送错误日志失败:', e)
    }
  }

  getErrors() { return this.errors }
  clearErrors() { this.errors = []; this.saveToStorage() }
}

// 初始化
const errorTracker = new ErrorTracker({
  endpoint: 'https://api.example.com/errors',
  maxErrors: 50
})

15.2 用户行为分析

/**
 * 用户行为分析
 */
class Analytics {
  constructor(options = {}) {
    this.enabled = options.enabled ?? true
    this.events = []
    this.sessionId = `${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
    this.startTime = Date.now()
  }

  track(eventName, properties = {}) {
    if (!this.enabled) return

    const event = {
      name: eventName,
      properties,
      timestamp: Date.now(),
      sessionId: this.sessionId,
      sessionDuration: Date.now() - this.startTime
    }

    this.events.push(event)
    this.saveToStorage()
    console.log('[Analytics] 事件:', eventName, properties)
  }

  // 常用事件追踪
  trackPageView(page) { this.track('page_view', { page }) }
  trackButtonClick(buttonId, buttonText) { this.track('button_click', { buttonId, buttonText }) }
  trackFeatureUse(feature) { this.track('feature_use', { feature }) }
  trackAPICall(endpoint, duration, success) { this.track('api_call', { endpoint, duration, success }) }

  async saveToStorage() {
    const recentEvents = this.events.slice(-1000)
    await chrome.storage.local.set({ analyticsEvents: recentEvents })
  }

  async getStats() {
    const events = this.events
    return {
      totalEvents: events.length,
      eventsByType: events.reduce((acc, e) => ({ ...acc, [e.name]: (acc[e.name] || 0) + 1 }), {}),
      sessionsCount: new Set(events.map(e => e.sessionId)).size
    }
  }
}

// 使用示例
const analytics = new Analytics({ enabled: true })
analytics.trackPageView('sidebar')
analytics.trackFeatureUse('ai-chat')

15.3 性能监控

/**
 * 性能监控
 */
class PerformanceMonitor {
  constructor() {
    this.metrics = []
  }

  async measure(name, fn) {
    const start = performance.now()
    try {
      const result = await fn()
      this.record(name, performance.now() - start, true)
      return result
    } catch (error) {
      this.record(name, performance.now() - start, false, error.message)
      throw error
    }
  }

  record(name, duration, success, error = null) {
    this.metrics.push({ name, duration, success, error, timestamp: Date.now() })
    if (this.metrics.length > 500) this.metrics.shift()
  }

  getAverageTime(name) {
    const relevant = this.metrics.filter(m => m.name === name)
    if (!relevant.length) return 0
    return relevant.reduce((sum, m) => sum + m.duration, 0) / relevant.length
  }

  getSuccessRate(name) {
    const relevant = this.metrics.filter(m => m.name === name)
    if (!relevant.length) return 0
    return (relevant.filter(m => m.success).length / relevant.length) * 100
  }

  getReport() {
    const names = [...new Set(this.metrics.map(m => m.name))]
    return names.map(name => ({
      name,
      count: this.metrics.filter(m => m.name === name).length,
      averageTime: this.getAverageTime(name).toFixed(2) + 'ms',
      successRate: this.getSuccessRate(name).toFixed(1) + '%'
    }))
  }
}

// 使用示例
const perfMonitor = new PerformanceMonitor()

// 测量 API 调用
const response = await perfMonitor.measure('api_chat', async () => {
  return await fetch('/api/chat', { method: 'POST', body: JSON.stringify(data) })
})

// 获取性能报告
console.table(perfMonitor.getReport())

十六、最佳实践总结

16.1 安全建议

不要使用 eval() 或动态执行远程代码
验证所有输入，防止 XSS 攻击
最小权限原则，只申请必要的权限
加密敏感数据 存储前进行加密

16.2 性能优化

Service Worker 休眠处理：使用 chrome.alarms 保持活跃
批量存储操作：合并多次写入
懒加载：按需加载模块
使用 IndexedDB：存储大量数据

16.3 用户体验

提供设置页面：让用户自定义行为
国际化：支持多语言
优雅降级：处理权限被拒绝的情况
清晰的错误提示：帮助用户理解问题

十七、常见问题与解决方案

Q1: Service Worker 频繁休眠怎么办？

chrome.alarms.create('keepAlive', { periodInMinutes: 0.5 })
chrome.alarms.onAlarm.addListener((alarm) => {
  if (alarm.name === 'keepAlive') console.log('保持活跃')
})

Q2: 消息发送后没有响应？

// 确保返回 true 以支持异步响应
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  handleAsync(message).then(sendResponse)
  return true // ← 这很重要！
})

Q3: Content Script 无法接收消息？

// 确保 Content Script 已注入
async function sendToContentScript(tabId, message) {
  try {
    await chrome.scripting.executeScript({
      target: { tabId },
      files: ['content-script.js']
    })
  } catch {}
  return chrome.tabs.sendMessage(tabId, message)
}

Q4: 如何在 Service Worker 中持久化数据？

// 不要使用全局变量，使用 chrome.storage
async function getData(key) {
  const result = await chrome.storage.local.get(key)
  return result[key]
}

十八、参考资源

官方文档

开发工具

常用 Chrome API 速查

API	用途	权限
chrome.runtime	扩展生命周期、消息通信	-
chrome.storage	数据存储	storage
chrome.tabs	标签页管理	tabs
chrome.sidePanel	侧边栏	sidePanel
chrome.action	工具栏图标	-
chrome.contextMenus	右键菜单	contextMenus
chrome.notifications	系统通知	notifications
chrome.alarms	定时器	alarms
chrome.scripting	脚本注入	scripting
chrome.declarativeNetRequest	网络请求拦截	declarativeNetRequest
chrome.offscreen	离屏文档	offscreen
chrome.i18n	国际化	-

总结

本文系统性地介绍了 Chrome 扩展开发的核心知识：

项目结构：manifest.json 配置、各文件职责
核心组件：Background Service Worker、Content Script、Side Panel、Popup
消息通信：runtime.sendMessage、tabs.sendMessage、Port 长连接
数据存储：chrome.storage API、IndexedDB
网络请求：HTTP 封装、流式 AI 对话
安全实践：输入验证、加密存储、权限最小化
高级 API：declarativeNetRequest、Offscreen Documents
国际化：i18n 支持
现代工具链：Vite + CRXJS、TypeScript、React/Vue
监控与分析：错误追踪、用户行为分析、性能监控
发布流程：Chrome Web Store 发布步骤

本文基于实际项目经验整理，代码示例均经过测试验证。如有问题欢迎交流讨论。