Chrome扩展开发技能Skill chrome-extension

---

name: chrome-extension description: Chrome扩展（Manifest V3）性能和代码质量指南。在编写、审查或重构Chrome扩展代码时使用，包括服务工作者、内容脚本、消息传递、存储API、TypeScript模式和测试。

Chrome扩展最佳实践

全面的Chrome扩展（Manifest V3）性能和代码质量指南。包含12个类别中的67条规则，按影响优先级排序，以指导自动化重构和代码生成。

何时应用

在以下情况下参考这些指南：

• 编写新的Chrome扩展代码
• 从Manifest V2迁移到Manifest V3
• 优化服务工作者生命周期和状态管理
• 实现内容脚本以进行页面交互
• 调试扩展中的性能问题

规则类别按优先级

优先级	类别	影响	前缀
1	服务工作者生命周期	关键	sw-
2	内容脚本优化	关键	content-
3	消息传递效率	高	msg-
4	存储操作	高	storage-
5	网络与权限	中高	net-
6	内存管理	中	mem-
7	UI性能	中	ui-
8	API使用模式	低中	api-
9	代码风格与命名	中	style-
10	组件模式	中	comp-
11	错误处理	高	err-
12	测试模式	中	test-

快速参考

1. 服务工作者生命周期（关键）

• sw-persist-state-storage - 使用chrome.storage持久化状态，而不是全局变量
• sw-avoid-keepalive - 避免人为的服务工作者保持活动模式
• sw-use-alarms-api - 使用chrome.alarms代替setTimeout/setInterval
• sw-return-true-async - 从消息监听器返回true以进行异步响应
• sw-register-listeners-toplevel - 在顶层注册事件监听器
• sw-use-offscreen-for-dom - 使用离屏文档进行DOM API

2. 内容脚本优化（关键）

• content-use-specific-matches - 使用特定的URL匹配模式
• content-use-document-idle - 使用document_idle进行内容脚本注入
• content-programmatic-injection - 优先使用程序化注入而非清单声明
• content-minimize-script-size - 最小化内容脚本包大小
• content-batch-dom-operations - 批量DOM操作以最小化重排
• content-use-mutation-observer - 使用MutationObserver代替轮询

3. 消息传递效率（高）

• msg-use-ports-for-frequent - 使用端口连接进行频繁消息交换
• msg-minimize-payload-size - 最小化消息负载大小
• msg-debounce-frequent-events - 在消息传递前对高频事件进行防抖
• msg-check-lasterror - 始终检查chrome.runtime.lastError
• msg-avoid-broadcast-to-all-tabs - 避免向所有标签页广播消息

4. 存储操作（高）

• storage-batch-operations - 批量存储操作而非单独调用
• storage-choose-correct-type - 根据使用案例选择正确的存储类型
• storage-cache-frequently-accessed - 缓存频繁访问的存储值
• storage-use-session-for-temp - 使用storage.session存储临时运行时数据
• storage-avoid-storing-large-blobs - 避免存储大型二进制blob

5. 网络与权限（中高）

• net-use-declarativenetrequest - 使用declarativeNetRequest代替webRequest
• net-request-minimal-permissions - 请求最少必需的权限
• net-use-activetab - 使用activeTab权限而非广泛的主机权限
• net-limit-csp-modifications - 避免修改内容安全策略头

6. 内存管理（中）

• mem-cleanup-event-listeners - 在内容脚本卸载时清理事件监听器
• mem-avoid-detached-dom - 避免持有分离的DOM节点引用
• mem-avoid-closure-leaks - 避免意外闭包内存泄漏
• mem-clear-intervals-timeouts - 在清理时清除间隔和超时
• mem-use-weak-collections - 使用WeakMap和WeakSet进行DOM元素引用

7. UI性能（中）

• ui-minimize-popup-bundle - 最小化弹出窗口包大小以实现快速启动
• ui-render-with-cached-data - 使用缓存数据首先渲染弹出窗口UI
• ui-batch-badge-updates - 批量徽章更新以避免闪烁
• ui-use-options-page-lazy - 懒加载选项页面部分

8. API使用模式（低中）

• api-use-promises-over-callbacks - 使用基于Promise的API调用而非回调
• api-query-tabs-efficiently - 使用特定过滤器查询标签页
• api-avoid-redundant-api-calls - 避免在循环中进行冗余API调用
• api-use-alarms-minperiod - 遵守alarms API最小周期
• api-handle-context-invalidated - 处理扩展上下文无效错误
• api-use-declarative-content - 使用declarative content API进行页面操作

9. 代码风格与命名（中）

• style-boolean-naming - 对布尔变量使用is/has/should前缀
• style-cache-naming - 使用一致的缓存变量命名
• style-constants - 为魔法值定义常量
• style-directory-structure - 按功能/层组织代码
• style-file-naming - 使用一致的文件命名约定
• style-function-naming - 使用描述性函数名称
• style-import-type - 对类型使用仅类型导入
• style-index-entry-points - 对模块入口点使用索引文件
• style-message-enums - 对消息类型使用枚举
• style-type-naming - 对类型和接口使用PascalCase

10. 组件模式（中）

• comp-adapter-interface - 对浏览器API使用适配器模式
• comp-content-script-structure - 一致地结构内容脚本
• comp-css-class-patterns - 使用BEM或带前缀的CSS类
• comp-manager-class - 对复杂状态使用管理器类
• comp-type-guards - 对运行时验证使用类型守卫
• comp-ui-components - 创建可重用的UI组件

11. 错误处理（高）

• err-context-invalidation - 处理扩展上下文无效
• err-early-return - 对错误处理使用早期返回
• err-null-coalescing - 对默认值使用空值合并
• err-promise-barrier - 对协调使用Promise屏障
• err-storage-operations - 处理存储操作失败
• err-url-parsing - 使用try/catch安全解析URL
• err-validation-pattern - 在边界验证输入

12. 测试模式（中）

• test-browser-api-mocking - 在测试中模拟chrome API
• test-organization - 按功能组织测试
• test-validation-functions - 彻底测试验证函数

如何使用

阅读各个参考文件以获取详细解释和代码示例：

• 部分定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

完整编译文档

有关包含所有规则的单文档完整指南，请参阅AGENTS.md。

参考文件

文件	描述
AGENTS.md	包含所有规则的完整编译指南
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息