chrome-extension

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 - 避免存储大型二进制数据

5. 网络与权限（中高）

• net-use-declarativenetrequest - 使用 declarativeNetRequest，而非 webRequest
• net-request-minimal-permissions - 仅申请必需的最低权限
• net-use-activetab - 使用 activeTab 权限，而非宽泛的主机权限
• net-limit-csp-modifications - 避免修改内容安全策略（CSP）标头

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 - 使用声明式内容 API 执行页面操作

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

• 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 - 使用 index 文件作为模块入口点
• style-message-enums - 使用枚举表示消息类型
• style-type-naming - 类型和接口使用 PascalCase

10. 组件模式（MEDIUM）

• 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. 错误处理（HIGH）

• 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. 测试模式（MEDIUM）

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

使用方法

阅读各个参考文件，了解详细说明和代码示例：

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

完整汇编文档

如需查看包含所有规则的完整指南，请参阅 AGENTS.md。

参考文件

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