谷歌浏览器扩展开发指南：从 Manifest V3 到上架 Chrome Web Store

my-extension/
├── manifest.json         # ★ 入口配置（V3 必备）
├── service-worker.js     # 后台逻辑
├── content-script.js     # 注入到网页里跑的脚本
├── popup/
│   ├── popup.html        # 点击图标弹出的小窗
│   ├── popup.js
│   └── popup.css
├── options/
│   └── options.html      # 设置页面
└── icons/
    ├── 16.png
    ├── 48.png
    └── 128.png

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "description": "A minimal Chrome Extension",

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

  "action": {
    "default_popup": "popup/popup.html",
    "default_title": "Click me"
  },

  "background": {
    "service_worker": "service-worker.js"
  },

  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "js":      ["content-script.js"],
      "run_at":  "document_idle"
    }
  ],

  "permissions": [
    "storage",
    "activeTab",
    "scripting"
  ],

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

  "options_page": "options/options.html",

  "web_accessible_resources": [
    {
      "resources": ["images/injected.png"],
      "matches":   ["<all_urls>"]
    }
  ]
}

┌──────────────────────────────────────────────────────────┐
│ ① Service Worker (后台)                                   │
│    - 没有 DOM, 不能 querySelector                         │
│    - 可访问所有 chrome.* API                              │
│    - 不活跃时会被回收, 事件来时重启                       │
└──────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────┐
│ ② Content Script (注入到网页里)                            │
│    - 能读写页面 DOM                                       │
│    - 与页面 JS 在「隔离世界」运行 (变量互不可见)         │
│    - 只能用部分 chrome.* (主要是 chrome.runtime/storage) │
└──────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────┐
│ ③ Popup / Options (扩展的页面)                            │
│    - 普通 HTML, 完整 DOM                                  │
│    - 可访问所有 chrome.* API                              │
│    - 关掉 popup 状态就丢, 用 chrome.storage 持久化       │
└──────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────┐
│ ④ DevTools 页 / Sidepanel 等特殊场景                     │
│    - 对应专门的 chrome.devtools / sidePanel API          │
└──────────────────────────────────────────────────────────┘

// service-worker.js

// 扩展首次安装 / 更新
chrome.runtime.onInstalled.addListener((details) => {
  console.log('Installed:', details.reason)  // install / update / chrome_update
  chrome.storage.local.set({ visits: 0 })
})

// 监听来自其他上下文的消息
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.type === 'GET_VISITS') {
    chrome.storage.local.get('visits', (data) => {
      sendResponse({ visits: data.visits ?? 0 })
    })
    return true   // ★ 关键: 异步 sendResponse 必须 return true
  }
})

// 监听 tab 更新
chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
  if (changeInfo.status === 'complete' && tab.url?.startsWith('http')) {
    chrome.storage.local.get('visits', ({ visits = 0 }) => {
      chrome.storage.local.set({ visits: visits + 1 })
    })
  }
})

// 处理 action 图标点击 (没有 default_popup 时才触发)
chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: { tabId: tab.id },
    func:   () => alert('Hello from extension!'),
  })
})

// 创建一个定时任务（每分钟）
chrome.alarms.create('refresh', { periodInMinutes: 1 })

chrome.alarms.onAlarm.addListener((alarm) => {
  if (alarm.name === 'refresh') {
    fetch('https://api.example.com/data')
      .then(r => r.json())
      .then(data => chrome.storage.local.set({ data }))
  }
})

"content_scripts": [
  {
    "matches": ["https://github.com/*"],
    "js":      ["content-script.js"],
    "css":     ["overlay.css"],
    "run_at":  "document_idle"
  }
]

// service-worker.js 里调用
chrome.scripting.executeScript({
  target: { tabId },
  files: ['injected.js'],
})

// 或注入一段函数
chrome.scripting.executeScript({
  target: { tabId },
  func: (title) => { document.title = title },
  args: ['Hijacked!'],
})

chrome.scripting.executeScript({
  target: { tabId },
  files:  ['inject-into-page.js'],
  world:  'MAIN',   // ← 注入到网页自己的 JS world
})

// content-script.js
chrome.runtime.sendMessage({ type: 'PING' }, (response) => {
  console.log('Got reply:', response)
})

// service-worker.js
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.type === 'PING') {
    sendResponse({ ok: true, from: 'service worker' })
  }
})

// content-script.js
const port = chrome.runtime.connect({ name: 'data-stream' })
port.postMessage({ hello: 'sw' })
port.onMessage.addListener((msg) => console.log(msg))

// service-worker.js
chrome.runtime.onConnect.addListener((port) => {
  if (port.name === 'data-stream') {
    port.onMessage.addListener((msg) => {
      port.postMessage({ echo: msg })
    })
  }
})

chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.type === 'FETCH') {
    fetch(msg.url)
      .then(r => r.text())
      .then(text => sendResponse({ text }))   // 异步回调
    return true  // ★ 必须 return true, 否则 sendResponse 失效
  }
})

// 写
await chrome.storage.local.set({ user: { name: 'Alice', theme: 'dark' } })

// 读
const { user } = await chrome.storage.local.get('user')

// 监听变化
chrome.storage.onChanged.addListener((changes, area) => {
  for (const key in changes) {
    console.log(`${area}.${key}: ${changes[key].oldValue} → ${changes[key].newValue}`)
  }
})

{
  "permissions": [
    "storage",       // 用 chrome.storage
    "activeTab",     // 当前 tab 临时权限（不需要 host_permissions）
    "scripting",     // 用 chrome.scripting.executeScript
    "tabs",          // 读 tab 详细信息（url 等）
    "alarms",
    "notifications",
    "contextMenus",
    "downloads",
    "clipboardWrite"
  ],
  "host_permissions": [
    "https://*.example.com/*",
    "https://api.github.com/*"
  ],
  "optional_host_permissions": [
    "<all_urls>"     // 用户安装后才动态请求
  ]
}

"declarative_net_request": {
  "rule_resources": [{
    "id": "ads",
    "enabled": true,
    "path": "rules.json"
  }]
}

// rules.json
[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {
      "urlFilter": "||doubleclick.net^",
      "resourceTypes": ["script", "image"]
    }
  }
]

npm create vite@latest my-ext -- --template react-ts
cd my-ext
npm i -D @crxjs/vite-plugin

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 })],
})

{
  "manifest_version": 3,
  "name": "GitHub PR Glance",
  "version": "1.0.0",
  "description": "Show open PR count for any GitHub repo page",
  "icons": { "128": "icons/128.png" },
  "action": { "default_popup": "popup.html" },
  "background": { "service_worker": "sw.js" },
  "content_scripts": [{
    "matches": ["https://github.com/*"],
    "js": ["content.js"],
    "run_at": "document_idle"
  }],
  "permissions": ["storage", "activeTab", "scripting"],
  "host_permissions": ["https://api.github.com/*"]
}

const match = location.pathname.match(/^\/([^/]+)\/([^/]+)/)
if (match) {
  const [, owner, repo] = match
  chrome.runtime.sendMessage({ type: 'PR_COUNT', owner, repo }, (res) => {
    const badge = document.createElement('div')
    badge.style.cssText = 'position:fixed;top:60px;right:20px;background:#000;color:#fff;padding:8px 12px;border-radius:6px;z-index:9999;font:13px/1 sans-serif'
    badge.textContent = `Open PRs: ${res.count}`
    document.body.appendChild(badge)
  })
}

chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.type === 'PR_COUNT') {
    fetch(`https://api.github.com/repos/${msg.owner}/${msg.repo}/pulls?state=open&per_page=1`)
      .then(r => {
        const link = r.headers.get('Link') || ''
        const m = link.match(/page=(\d+)>; rel="last"/)
        sendResponse({ count: m ? parseInt(m[1]) : 0 })
      })
    return true
  }
})

<!doctype html>
<html><body style="width:200px;padding:12px;font:14px/1.4 sans-serif">
  <h3 style="margin:0 0 8px">GitHub PR Glance</h3>
  <p>Open any GitHub repo to see open PR count.</p>
</body></html>

let count = 0   // ❌ 重启就归零
chrome.action.onClicked.addListener(() => count++)