chrome-extension-development

Chrome 扩展开发

此技能提供 Chrome 扩展开发的专业级指导，涵盖 JavaScript/TypeScript、浏览器扩展 API 和现代 Web 开发实践。

工作流：从零开始构建 Chrome 扩展

1. 初始化项目 — 创建目录结构，包含 manifest.json、后台服务工作线程、内容脚本和弹出窗口文件。
2. 配置清单文件 — 按照 Manifest V3 格式定义权限、内容脚本匹配规则、服务工作线程注册信息和操作设置。
3. 实现后台服务工作线程 — 使用 chrome.* API 设置扩展生命周期、消息传递和闹钟的事件侦听器。
4. 构建内容脚本 — 编写与网页 DOM 交互的脚本，通过 chrome.runtime.sendMessage 与后台工作线程通信，并遵循 CSP。
5. 创建弹出窗口 UI — 设计弹出窗口 HTML/CSS，并将其交互功能连接到后台和内容脚本。
6. 添加存储和状态管理 — 使用 chrome.storage.local 或 chrome.storage.sync 持久化用户设置和扩展状态。
7. 测试和调试 — 通过 chrome://extensions 加载未打包的扩展，使用 Chrome DevTools 检查服务工作线程和内容脚本，并运行单元测试。
8. 打包和发布 — 准备商店素材（图标、屏幕截图、描述），创建隐私政策，并提交到 Chrome Web Store。

示例：最简 Manifest V3 配置

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "description": "A sample Chrome extension using Manifest V3",
  "permissions": ["storage", "activeTab"],
  "action": {
    "default_popup": "popup/popup.html",
    "default_icon": {
      "16": "icons/icon16.png",
      "48": "icons/icon48.png",
      "128": "icons/icon128.png"
    }
  },
  "background": {
    "service_worker": "background/service-worker.js",
    "type": "module"
  },
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "js": ["content/content-script.js"],
      "css": ["content/styles.css"]
    }
  ]
}

示例：带消息传递功能的后台服务工作线程

// background/service-worker.ts

// Listen for extension install or update
chrome.runtime.onInstalled.addListener((details) => {
  if (details.reason === 'install') {
    chrome.storage.local.set({ initialized: true, count: 0 });
    console.log('Extension installed');
  }
});

// Handle messages from content scripts or popup
chrome.runtime.onMessage.addListener(
  (message: { type: string; payload?: unknown }, sender, sendResponse) => {
    if (message.type === 'GET_COUNT') {
      chrome.storage.local.get('count', (result) => {
        sendResponse({ count: result.count ?? 0 });
      });
      return true; // keep message channel open for async response
    }

    if (message.type === 'INCREMENT') {
      chrome.storage.local.get('count', (result) => {
        const newCount = (result.count ?? 0) + 1;
        chrome.storage.local.set({ count: newCount }, () => {
          sendResponse({ count: newCount });
        });
      });
      return true;
    }
  }
);

// Schedule periodic tasks with chrome.alarms
chrome.alarms.create('sync-data', { periodInMinutes: 30 });
chrome.alarms.onAlarm.addListener((alarm) => {
  if (alarm.name === 'sync-data') {
    console.log('Running scheduled sync');
  }
});

代码风格和结构

• 编写清晰、模块化且带有适当类型定义的 TypeScript 代码
• 遵循函数式编程模式；避免使用类
• 使用描述性变量名（例如，isLoading、hasPermission）
• 按逻辑组织文件：弹出窗口、后台、内容脚本、工具
• 实现适当的错误处理和日志记录
• 使用 JSDoc 注释记录代码

架构和最佳实践

• 严格遵循 Manifest V3 规范
• 在后台、内容脚本和弹出窗口之间划分职责
• 遵循最小权限原则配置权限
• 使用现代构建工具（webpack/vite）进行开发
• 实施适当的版本控制和变更管理

Chrome API 用法

• 正确使用 chrome.* API（storage、tabs、runtime 等）
• 使用 Promise 处理异步操作
• 对后台脚本使用 Service Worker（MV3 要求）
• 使用 chrome.alarms 实现计划任务
• 使用 chrome.action API 实现浏览器操作
• 妥善处理离线功能

安全和隐私

• 实施内容安全策略（CSP）
• 安全处理用户数据
• 防止 XSS 和注入攻击
• 在组件之间安全地传递消息
• 安全处理跨源请求
• 实施安全的数据加密
• 遵循 web_accessible_resources 最佳实践

性能和优化

• 尽量减少资源使用并避免内存泄漏
• 优化后台脚本性能
• 实施适当的缓存机制
• 高效处理异步操作
• 监控并优化 CPU/内存使用情况

UI 和用户体验

• 遵循 Material Design 指南
• 实现自适应弹出窗口
• 为用户提供清晰的反馈
• 支持键盘导航
• 确保正确显示加载状态
• 添加恰当的动画

国际化

• 使用 chrome.i18n API 进行翻译
• 遵循 _locales 结构
• 支持 RTL 语言
• 处理区域格式

无障碍访问

• 实现 ARIA 标签
• 确保足够的颜色对比度
• 支持屏幕阅读器
• 添加键盘快捷键

测试和调试

• 高效使用 Chrome DevTools
• 编写单元测试和集成测试
• 测试跨浏览器兼容性
• 监控性能指标
• 处理错误场景

发布和维护

• 准备商店详情和屏幕截图
• 撰写清晰的隐私政策
• 实施更新机制
• 处理用户反馈
• 维护文档

遵循官方文档

• 参考 Chrome Extension 文档
• 跟进 Manifest V3 的变更
• 遵循 Chrome Web Store 指南
• 关注 Chrome 平台更新

输出要求

• 提供清晰、可运行的代码示例
• 包含必要的错误处理
• 遵循安全最佳实践
• 确保跨浏览器兼容性
• 编写易于维护且可扩展的代码