wxt-browser-extensions

社区 WXT 浏览器扩展最佳实践

WXT 浏览器扩展开发的全面性能优化指南。包含 8 个类别中的 49 条规则，并按影响优先级排序，为自动重构和代码生成提供指导。已针对 WXT v0.20+ 更新。

适用场景

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

• 编写新的 WXT 浏览器扩展代码
• 实现后台 Service Worker 脚本
• 向网页注入内容脚本
• 设置扩展上下文之间的消息传递
• 配置清单权限和资源

按优先级划分的规则类别

优先级	类别	影响	前缀
1	Service Worker 生命周期	CRITICAL	svc-
2	内容脚本注入	CRITICAL	inject-
3	消息传递架构	HIGH	msg-
4	存储模式	HIGH	store-
5	打包优化	MEDIUM-HIGH	bundle-
6	清单配置	MEDIUM	manifest-
7	UI 性能	MEDIUM	ui-
8	TypeScript 模式	LOW-MEDIUM	ts-

快速参考

1. Service Worker 生命周期（CRITICAL）

• svc-register-listeners-synchronously - 同步注册监听器，以防遗漏事件
• svc-avoid-global-state - 使用存储代替内存状态
• svc-keep-alive-patterns - 在长时间运行的操作期间保持 Service Worker 存活
• svc-handle-install-update - 处理安装和更新生命周期事件
• svc-offscreen-documents - 使用离屏文档执行 DOM 操作
• svc-declarative-net-request - 使用声明式规则拦截网络请求

2. 内容脚本注入（CRITICAL）

• inject-use-main-function - 将运行时代码放在 main() 函数中
• inject-choose-correct-world - 适当选择 ISOLATED 或 MAIN 环境
• inject-run-at-timing - 配置合适的 runAt 时机
• inject-use-ctx-invalidated - 处理更新时的上下文失效
• inject-dynamic-registration - 使用运行时注册实现条件注入
• inject-all-frames - 配置 allFrames 以处理 iframe
• inject-spa-navigation - 使用 wxt:locationchange 处理 SPA 导航

3. 消息传递架构（HIGH）

• msg-type-safe-messaging - 使用 @webext-core/messaging 实现类型安全的协议
• msg-return-true-for-async - 异步消息处理程序返回 true（原始 API）
• msg-use-tabs-sendmessage - 使用 tabs.sendMessage 向内容脚本发送消息
• msg-use-ports-for-streams - 使用端口进行流式通信
• msg-handle-no-receiver - 处理缺少消息接收方的情况
• msg-avoid-circular-messages - 防止循环消息

4. 存储模式（HIGH）

• store-use-define-item - 使用 storage.defineItem 实现类型安全的访问
• store-choose-storage-area - 选择合适的存储区域
• store-batch-operations - 将相关数据组合到单个 defineItem 中
• store-watch-for-changes - 使用 watch() 实现响应式更新
• store-handle-quota-errors - 处理存储配额错误
• store-versioned-migrations - 使用版本控制进行架构迁移

5. Bundle 优化（MEDIUM-HIGH）

• bundle-split-entrypoints - 按入口点拆分代码
• bundle-analyze-size - 分析并监控 bundle 大小
• bundle-tree-shake-icons - 直接导入图标库
• bundle-externalize-wasm - 动态加载 WASM
• bundle-minify-content-scripts - 尽量减小内容脚本的体积

6. 清单配置（MEDIUM）

• manifest-minimal-permissions - 仅请求最少权限
• manifest-use-optional-permissions - 渐进式使用可选权限
• manifest-web-accessible-resources - 限定 Web 可访问资源的范围
• manifest-content-security-policy - 正确配置 CSP
• manifest-cross-browser-compatibility - 支持多种浏览器

7. UI 性能（MEDIUM）

• ui-use-shadow-dom - 使用 Shadow DOM 注入 UI
• ui-defer-rendering - 按需延迟渲染弹出窗口
• ui-cleanup-on-unmount - 卸载时清理 UI
• ui-sidepanel-persistence - 保留侧边栏状态
• ui-position-fixed-iframe - 使用 iframe 实现复杂 UI
• ui-avoid-layout-thrashing - 批量读取和写入 DOM

8. TypeScript 模式（LOW-MEDIUM）

• ts-use-imports-module - 使用 #imports 虚拟模块和自动导入
• ts-use-browser-not-chrome - 优先使用 browser 命名空间，而非 chrome
• ts-type-entrypoint-options - 显式声明入口点选项的类型
• ts-augment-browser-types - 为缺失的 API 扩充类型
• ts-strict-null-checks - 启用严格空值检查
• ts-import-meta-env - 使用 import.meta 获取构建信息
• ts-avoid-any - 避免在处理函数中使用 any 类型
• ts-path-aliases - 使用路径别名导入

使用方法

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

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

参考文件

文件	描述
references/_sections.md	分类定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息