WXT浏览器扩展性能优化指南Skill wxt-browser-extensions

---

name: wxt-browser-extensions description: WXT浏览器扩展性能优化指南。此技能应用于编写、审查或重构WXT浏览器扩展代码时，以确保最优性能模式。触发任务涉及WXT、浏览器扩展、内容脚本、服务工人、消息传递和扩展API。

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

WXT浏览器扩展开发的综合性能优化指南。包含49条规则，分为8个类别，按影响优先级排序，以指导自动化重构和代码生成。已更新至WXT v0.20+版本。

何时应用

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

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

规则类别按优先级

优先级	类别	影响	前缀
1	服务工人生命周期	关键	svc-
2	内容脚本注入	关键	inject-
3	消息架构	高	msg-
4	存储模式	高	store-
5	捆绑优化	中高	bundle-
6	清单配置	中	manifest-
7	UI性能	中	ui-
8	TypeScript模式	低中	ts-

快速参考

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

• svc-register-listeners-synchronously - 同步注册监听器以防止错过事件
• svc-avoid-global-state - 使用存储而非内存状态
• svc-keep-alive-patterns - 为长操作保持服务工人活跃
• svc-handle-install-update - 处理安装和更新生命周期事件
• svc-offscreen-documents - 使用离屏文档进行DOM操作
• svc-declarative-net-request - 使用声明式规则进行网络阻塞

2. 内容脚本注入（关键）

• 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. 消息架构（高）

• 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. 存储模式（高）

• 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-split-entrypoints - 按入口点拆分代码
• bundle-analyze-size - 分析和监控捆绑大小
• bundle-tree-shake-icons - 使用直接导入用于图标库
• bundle-externalize-wasm - 动态加载WASM
• bundle-minify-content-scripts - 最小化内容脚本大小

6. 清单配置（中）

• manifest-minimal-permissions - 请求最小权限
• manifest-use-optional-permissions - 逐步使用可选权限
• manifest-web-accessible-resources - 限定可访问的网络资源
• manifest-content-security-policy - 正确配置CSP
• manifest-cross-browser-compatibility - 支持多浏览器

7. UI性能（中）

• 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模式（低中）

• 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	版本和参考信息