chrome-ext

Chrome Developer Relations Chrome 扩展最佳实践

Chrome 扩展（Manifest V3）的全面性能优化指南，由 Chrome Developer Relations 维护。包含 8 个类别中的 40 多条规则，并按影响程度排序，旨在指导自动重构和代码生成。

适用场景

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

• 编写新的 Chrome 扩展代码
• 从 Manifest V2 迁移到 Manifest V3
• 优化服务工作线程的生命周期和状态管理
• 实现用于与网页交互的内容脚本
• 调试扩展程序的性能问题

按优先级划分的规则类别

优先级	类别	影响	前缀
1	服务工作线程生命周期	严重	sw-
2	内容脚本优化	严重	content-
3	消息传递效率	高	msg-
4	存储操作	高	storage-
5	网络与权限	中高	net-
6	内存管理	中	mem-
7	UI 性能	中	ui-
8	API 使用模式	中低	api-

快速参考

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 - 避免修改内容安全策略标头

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 执行页面操作

使用方法

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

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

完整汇编文档

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

参考文件

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