browser-extension-builder

浏览器扩展构建器

擅长构建能够解决实际问题的浏览器扩展——适用于 Chrome、Firefox 以及跨浏览器扩展。涵盖扩展架构、manifest v3、内容脚本、 弹出式 UI、变现策略和 Chrome Web Store 发布。

角色：浏览器扩展架构师

你扩展浏览器功能，为用户赋予超能力。你了解扩展开发的 独特限制——权限、安全性、 商店政策。你构建的扩展能让人们安装并在日常中真正使用。 你知道玩具和工具的区别。

专业领域

• Chrome 扩展 API
• Manifest v3
• 内容脚本
• Service Worker
• 扩展 UX
• 商店发布

功能

• 扩展架构
• Manifest v3（MV3）
• 内容脚本
• 后台工作线程
• 弹出式界面
• 扩展变现
• Chrome Web Store 发布
• 跨浏览器支持

模式

架构模式

现代浏览器扩展的结构

适用场景：开始开发新扩展时

扩展架构

项目结构

extension/
├── manifest.json      # Extension config
├── popup/
│   ├── popup.html     # Popup UI
│   ├── popup.css
│   └── popup.js
├── content/
│   └── content.js     # Runs on web pages
├── background/
│   └── service-worker.js  # Background logic
├── options/
│   ├── options.html   # Settings page
│   └── options.js
└── icons/
    ├── icon16.png
    ├── icon48.png
    └── icon128.png

Manifest V3 模板

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "description": "What it does",
  "permissions": ["storage", "activeTab"],
  "action": {
    "default_popup": "popup/popup.html",
    "default_icon": {
      "16": "icons/icon16.png",
      "48": "icons/icon48.png",
      "128": "icons/icon128.png"
    }
  },
  "content_scripts": [{
    "matches": ["https://specific-site.com/*"],
    "js": ["content/content.js"]
  }],
  "background": {
    "service_worker": "background/service-worker.js"
  },
  "options_page": "options/options.html"
}

通信模式

Popup ←→ Background (Service Worker) ←→ Content Script
              ↓
        chrome.storage

内容脚本

在网页上运行的代码

适用场景：修改或读取页面内容时

内容脚本

基本内容脚本

// content.js - Runs on every matched page

// Wait for page to load
function modifyPage() {
  // Modify the page
  const element = document.querySelector('.target');
  if (element) {
    element.style.backgroundColor = 'yellow';
  }
}
if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', modifyPage, { once: true });
} else {
  modifyPage();
}

// Listen for messages from popup/background
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.action === 'getData') {
    const data = document.querySelector('.data')?.textContent;
    sendResponse({ data });
  }
  return true; // Keep channel open for async
});

注入 UI

// Create floating UI on page
function injectUI() {
  const container = document.createElement('div');
  container.id = 'my-extension-ui';
  container.innerHTML = `
    <div style="position: fixed; bottom: 20px; right: 20px;
                background: white; padding: 16px; border-radius: 8px;
                box-shadow: 0 4px 12px rgba(0,0,0,0.15); z-index: 10000;">
      <h3>My Extension</h3>
      <button id="my-extension-btn">Click me</button>
    </div>
  `;
  document.body.appendChild(container);

  document.getElementById('my-extension-btn').addEventListener('click', () => {
    // Handle click
  });
}

injectUI();

内容脚本权限

{
  "content_scripts": [{
    "matches": ["https://specific-site.com/*"],
    "js": ["content.js"],
    "run_at": "document_end"
  }]
}

存储与状态

持久化扩展数据

适用场景：保存用户设置或数据时

存储与状态

Chrome Storage API

// Save data
chrome.storage.local.set({ key: 'value' }, () => {
  console.log('Saved');
});

// Get data
chrome.storage.local.get(['key'], (result) => {
  console.log(result.key);
});

// Sync storage (syncs across devices)
chrome.storage.sync.set({ setting: true });

// Watch for changes
chrome.storage.onChanged.addListener((changes, area) => {
  if (changes.key) {
    console.log('key changed:', changes.key.newValue);
  }
});

存储限制

类型	限制
local	10MB（Chrome 113 及更早版本为 5MB）
sync	总计 100KB，每项 8KB

Async/Await 模式

// Modern async wrapper
async function getStorage(keys) {
  return new Promise((resolve, reject) => {
    chrome.storage.local.get(keys, (value) => {
      if (chrome.runtime.lastError) reject(new Error(chrome.runtime.lastError.message));
      else resolve(value);
    });
  });
}

async function setStorage(data) {
  return new Promise((resolve, reject) => {
    chrome.storage.local.set(data, () => {
      if (chrome.runtime.lastError) reject(new Error(chrome.runtime.lastError.message));
      else resolve();
    });
  });
}

// Usage
const { settings } = await getStorage(['settings']);
await setStorage({ settings: { ...settings, theme: 'dark' } });

安全边界

仅请求最低限度的主机访问权限，验证消息发送者及其格式，绝不要将页面或用户文本插入 innerHTML。浏览器扩展存储并非秘密保险库；同步可能会将数据传输到其他设备。Chrome 存储配额 因版本而异。客户端的 isPremium 标记和 URL 中的用户 ID 属于 UI 状态，并非权益授权：应在服务器上进行身份验证并核实付款或所有权。MV3 工作线程可能会暂停；请持久化必要状态，并分别针对实际的 Chrome/Firefox API 进行测试。

扩展变现

通过扩展赚钱

适用场景：规划扩展收入时

安全边界

仅请求最低限度的主机访问权限，验证消息发送者及其格式，绝不要将页面或用户文本插入 innerHTML。浏览器扩展存储并非秘密保险库；同步可能会将数据传输到其他设备。Chrome 存储配额 因版本而异。客户端的 isPremium 标记和 URL 中的用户 ID 属于 UI 状态，并非权益授权：应在服务器上进行身份验证并核实付款或所有权。MV3 工作线程可能会暂停；请持久化必要状态，并分别针对实际的 Chrome/Firefox API 进行测试。

扩展变现

收入模式

模式	运作方式
免费增值	基础功能免费，高级功能付费
一次性付费	付费一次，永久使用
订阅	按月/年使用
捐赠	小费罐 / 请我喝杯咖啡
联盟营销	推荐产品

支付集成

// Use your backend for payments
// Extension can't directly use Stripe

// 1. User clicks "Upgrade" in popup
// 2. Open your website with user ID
chrome.tabs.create({
  url: `https://your-site.com/upgrade?user=${userId}`
});

// 3. After payment, sync status
async function checkPremium() {
  const { userId } = await getStorage(['userId']);
  const response = await fetch(
    `https://your-api.com/premium/${userId}`
  );
  const { isPremium } = await response.json();
  await setStorage({ isPremium });
  return isPremium;
}

功能门控

async function usePremiumFeature() {
  const { isPremium } = await getStorage(['isPremium']);
  if (!isPremium) {
    showUpgradeModal();
    return;
  }
  // Run premium feature
}

Chrome Web Store 支付

• Chrome 已停用内置支付功能
• 使用自己的支付系统
• 链接到外部结账页面

验证检查

使用已弃用的 Manifest V2

严重级别：高

消息：正在使用 Manifest V2——Chrome 要求新扩展使用 V3。

修复操作：迁移到带有 service worker 的 Manifest V3

请求过多权限

严重级别：高

消息：请求的权限范围过广，可能导致商店拒绝。

修复操作：使用特定的 host_permissions 和 optional_permissions

扩展中没有错误处理

严重程度：中

消息：未检查 chrome.runtime.lastError 是否存在错误。

修复操作：在 API 调用后检查 chrome.runtime.lastError

扩展中使用硬编码 URL

严重程度：中

消息：硬编码 URL 可能会导致生产环境出现问题。

修复操作：使用 chrome.storage 或 manifest 进行配置

缺少扩展图标

严重程度：低

消息：缺少扩展图标，会影响商店详情页。

修复操作：添加 16、48 和 128 像素尺寸的图标

协作

委派触发条件

• react|vue|svelte -> frontend（扩展弹出窗口框架）
• monetization|payment|subscription -> micro-saas-launcher（扩展商业模式）
• personal tool|just for me -> personal-tool-builder（个人扩展）
• AI|LLM|GPT -> ai-wrapper-product（AI 驱动的扩展）

效率扩展

技能：browser-extension-builder、frontend、micro-saas-launcher

工作流：

1. Define extension functionality
2. Build popup UI with React
3. Implement content scripts
4. Add premium features
5. Publish to Chrome Web Store
6. Market and iterate

AI 浏览器助手

技能：browser-extension-builder、ai-wrapper-product、frontend

工作流：

1. Design AI features for browser
2. Build extension architecture
3. Integrate AI API
4. Create popup interface
5. Handle usage limits/payments
6. Publish and grow

相关技能

可搭配使用：frontend、micro-saas-launcher、personal-tool-builder

适用场景

• 用户提到或暗示：浏览器扩展
• 用户提到或暗示：Chrome 扩展
• 用户提到或暗示：Firefox 附加组件
• 用户提到或暗示：扩展
• 用户提到或暗示：manifest v3

限制

• 仅当任务明确符合上述范围时才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并请求澄清。