【工具分享】浏览器插件开发优化：从框架选择到实战技能全指南

# WXT
npx wxt@latest init my-extension

# Plasmo
pnpm create plasmo

# CRXJS
npm create crxjs@latest

# Extension.js
npx extension dev https://github.com/example/sample

// 发送方（Content Script 或 Popup）
const response = await chrome.runtime.sendMessage({ type: "GET_SETTINGS" });

// 接收方（Service Worker）
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === "GET_SETTINGS") {
    chrome.storage.sync.get("settings").then(sendResponse);
    return true; // 异步 sendResponse 必须返回 true 保持通道
  }
});

// Content Script 连接 Service Worker
const port = chrome.runtime.connect({ name: "sync-channel" });
port.postMessage({ action: "start-sync" });
port.onMessage.addListener((response) => { /* ... */ });

// Service Worker 接受连接
chrome.runtime.onConnect.addListener((port) => {
  port.onMessage.addListener((msg) => {
    port.postMessage({ status: "syncing" });
  });
});

// MAIN world 注入 — 访问页面 React 内部
await chrome.scripting.executeScript({
  target: { tabId },
  world: "MAIN",
  func: () => {
    const fiber = document.getElementById("root")._reactRootContainer;
    document.dispatchEvent(new CustomEvent("ext:page-data", {
      detail: { hasReact: !!fiber }
    }));
  }
});

function createIsolatedUI() {
  const host = document.createElement("div");
  host.id = "my-ext-host";
  const shadow = host.attachShadow({ mode: "closed" }); // closed = 页面 JS 无法访问
  shadow.innerHTML = `
    <style>
      :host { all: initial !important; position: fixed !important; z-index: 2147483647 !important; }
      .panel { background: #fff; border-radius: 8px; padding: 16px; }
    </style>
    <div class="panel">Extension UI</div>
  `;
  document.body.appendChild(host);
}

// manifest.json
{ "permissions": ["activeTab", "scripting"] }

// Service Worker — Action 点击时注入
chrome.action.onClicked.addListener(async (tab) => {
  await chrome.scripting.executeScript({
    target: { tabId: tab.id },
    func: () => { document.body.style.background = "red"; }
  });
});

// manifest.json
{
  "optional_permissions": ["topSites"],
  "optional_host_permissions": ["https://*/*"]
}

// 用户操作触发时请求
chrome.permissions.request({
  permissions: ["topSites"],
  origins: ["https://www.google.com/"]
}, (granted) => { /* ... */ });

chrome.runtime.onInstalled.addListener((details) => {
  if (details.reason === "update") {
    migrateStorage(details.previousVersion);
  }
});

async function migrateStorage(previousVersion) {
  const { schemaVersion } = await chrome.storage.local.get("schemaVersion");
  if (!schemaVersion || schemaVersion < 2) {
    const oldData = await chrome.storage.local.get(null);
    const newData = transformData(oldData);
    await chrome.storage.local.set({ ...newData, schemaVersion: 2 });
  }
}

// Offscreen Document — 需要 DOM 操作时
chrome.offscreen.createDocument({
  url: "offscreen.html",
  reasons: ["AUDIO_PLAYBACK"],
  justification: "播放提示音"
});

// test/setup.ts
import { vi } from "vitest";

(globalThis as any).chrome = {
  storage: {
    local: {
      get: vi.fn().mockResolvedValue({}),
      set: vi.fn().mockResolvedValue(undefined),
    },
  },
  runtime: {
    onMessage: { addListener: vi.fn() },
    sendMessage: vi.fn().mockResolvedValue(undefined),
    getURL: vi.fn((path) => `chrome-extension://fake-id/${path}`),
  },
};

// e2e/fixtures.ts
import { test as base, chromium } from "@playwright/test";
import path from "path";

export const test = base.extend({
  context: async ({}, use) => {
    const extensionPath = path.resolve(__dirname, "../dist");
    const context = await chromium.launchPersistentContext("", {
      headless: false, // Chrome 132+ 支持新 headless 模式
      args: [
        `--disable-extensions-except=${extensionPath}`,
        `--load-extension=${extensionPath}`,
      ],
    });
    await use(context);
    await context.close();
  },
  extensionId: async ({ context }, use) => {
    let sw = context.serviceWorkers()[0];
    if (!sw) sw = await context.waitForEvent("serviceworker");
    const id = sw.url().split("/")[2];
    await use(id);
  },
});

# GitHub Actions 简例
- run: pnpm install
- run: pnpm test
- run: npx playwright install --with-deps chromium
- run: npx playwright test
- run: pnpm build
- uses: puzzlers-labs/chrome-webstore-publish@v3

{
  "content_security_policy": {
    "extension_pages": "default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self';"
  }
}

// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      input: {
        background: resolve(__dirname, "src/background.ts"),
        content: resolve(__dirname, "src/content.ts"),
        popup: resolve(__dirname, "popup.html"),
      },
      output: {
        entryFileNames: "[name].js",
        format: "iife",          // 关键：IIFE 而非 ES 模块
      },
    },
    target: "chrome120",
  },
});

1. /create-chrome-extension:cce-init      → 访谈、裁剪、确认通过
2. /create-chrome-extension:cws-content   → 填写商店列表
3. /create-chrome-extension:cws-screens   → 渲染截图
4. /create-chrome-extension:cws-video     → 制作宣传视频（可选）
5. /create-chrome-extension:setup-cws-credentials → OAuth 配置（一次性）
6. /create-chrome-extension:cws-ship      → 版本同步、上传、轮询

# 1. 脚手架工厂仓库
npx create-chrome-extension my-extension
cd my-extension

# 2. 安装 Claude Code 插件
/plugin marketplace add codyhxyz/create-chrome-extension
/plugin install create-chrome-extension@create-chrome-extension

npx @open-gitagent/gitagent run -r https://github.com/AJAmit17/chrome-extension-builder

/* CSS 自定义属性 + prefers-color-scheme */
:root {
  --bg: #fff;
  --text: #1a1a1a;
}
@media (prefers-color-scheme: dark) {
  :root {
    --bg: #1a1a1a;
    --text: #e5e5e5;
  }
}

_locales/
  en/
    messages.json
  zh/
    messages.json

{
  "extName": {
    "message": "My Extension",
    "description": "扩展名称"
  }
}

// JS 中使用
chrome.i18n.getMessage("extName");

// Manifest/HTML 中使用
// __MSG_extName__