关于 service-worker
此技能为使用 service worker 和 Workbox 构建 Web 应用的开发者提供指导，涵盖缓存、离线支持、后台同步和推送通知。内容还包括常见策略、生命周期问题与浏览器支持注意事项。
主要功能
- 01Workbox 预缓存与缓存策略
- 02失败请求的后台同步
- 03推送通知与离线回退
- 04缓存过期及更新生命周期指导
适用场景
- 01为渐进式 Web 应用添加离线支持
- 02为资源和 API 响应选择缓存策略
- 03规划网络请求失败时的回退方案
- 04处理 service worker 更新和缓存清理
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/service-worker确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
references/background-sync.mdcaching-strategies.mdlifecycle.mdlocal-first-patterns.mdpush-notifications.mdstatic-routing.md详细介绍
Service Worker
概述
Service worker 是事件驱动脚本，在独立于主页面的线程中运行，可拦截网络请求、管理缓存并启用离线功能。Workbox v7.4（由 Chrome Aurora 团队维护）为底层 Cache API 和 fetch 事件处理提供了可用于生产环境的抽象。
适用场景： 需要离线支持的渐进式 Web 应用、需要推送通知的应用、后台数据同步、应用外壳缓存，以及通过静态路由优化网络请求。
不适用场景： 由 CDN 提供服务的简单静态网站、没有离线需求的服务端渲染应用、无法接受过期数据的应用（使用仅网络策略），以及缓存复杂度尚无必要的原型。
快速参考
| 模式 | API / 工具 | 要点 |
|---|---|---|
| 注册 | navigator.serviceWorker.register() | 在 window 上下文中注册，作用域默认为路径 |
| 预缓存 | workbox-precaching | 带修订哈希的应用外壳，在构建时注入 |
| 缓存优先 | CacheFirst 策略 | 静态资源、字体、图片 |
| 网络优先 | NetworkFirst 策略 | 需要保持最新的 API 响应 |
| 缓存并后台更新 | StaleWhileRevalidate 策略 | 平衡速度与内容新鲜度 |
| 后台同步 | workbox-background-sync | 恢复联网后重放失败的请求 |
| 推送通知 | Push API + Notifications API | VAPID 密钥、服务端推送、离线优先显示 |
| 静态路由 | 安装时调用 event.addRoutes() | 对已知路由绕过 fetch 处理程序 |
| 跳过等待 | self.skipWaiting() | 立即激活新的 SW，谨慎使用 |
| 声明控制客户端 | self.clients.claim() | 无需重新加载即可控制现有标签页 |
| 导航预加载 | navigationPreload.enable() | SW 启动期间并行发起网络请求 |
| 更新提示 | workbox-window Workbox 类 | 检测更新、提示用户，并通过 postMessage 向 SW 发送消息 |
| 离线回退 | workbox-recipes offlineFallback | 缓存和网络均不可用时提供回退页面 |
| 缓存过期 | workbox-expiration | 为每个缓存设置 maxEntries 和 maxAgeSeconds |
浏览器支持快速参考
| 功能 | Chrome | Firefox | Safari | Edge |
|---|---|---|---|---|
| Service Workers | 40+ | 44+ | 11.1+ | 17+ |
| Background Sync | 49+ | 不支持 | 不支持 | 79+ |
| Periodic Sync | 80+ | 不支持 | 不支持 | 80+ |
| Push API | 50+ | 44+ | 16.4+ | 17+ |
| Navigation Preload | 59+ | 99+ | 15.4+ | 18+ |
| Static Routing API | 123+ | 不支持 | 不支持 | 123+ |
| Background Fetch | 74+ | 不支持 | 不支持 | 79+ |
| Storage Persistence | 52+ | 55+ | 15.2+ | 79+ |
常见错误
| 错误 | 正确做法 |
|---|---|
| 使用 CacheFirst 缓存 API 响应 | 对动态数据使用 NetworkFirst 或 StaleWhileRevalidate |
| 无条件调用 skipWaiting | 激活前提示用户，避免中断正在进行的导航 |
| 不对预缓存清单进行版本管理 | 使用 workbox-build 或 workbox-webpack-plugin 注入修订哈希 |
| 忽略缓存存储空间限制 | 使用 workbox-expiration 插件实现缓存过期 |
| 在服务工作线程中使用同步访问句柄 | OPFS createSyncAccessHandle 仅适用于专用工作线程；请使用异步方法 |
| 假定 Background Sync 在所有环境中都能运行 | 仅支持 Chrome/Edge（约 80%）；请实现 navigator.onLine 回退 |
| 缓存没有大小限制的不透明响应 | 不透明响应会占用缓存配额；请使用 maxEntries 限制数量 |
| 未处理服务工作线程更新竞争 | 使用 workbox-window 与页面协调更新生命周期 |
| 在页面加载完成前注册 SW | 在 window load 事件中注册，以避免争抢带宽 |
| 让同步引擎的数据流经 SW 缓存 | 让同步引擎处理数据；SW 处理应用外壳和静态资源 |
| 激活时未清理旧缓存 | 在 activate 事件中删除过期缓存，以释放存储空间 |
| 缺少导航的离线回退 | 预缓存一个 offline.html，并在网络和缓存都失败时提供该页面 |
Workbox 软件包参考
| 软件包 | 用途 |
|---|---|
workbox-precaching | 构建时缓存资源并管理修订版本 |
workbox-routing | 匹配 URL 模式并路由策略 |
workbox-strategies | CacheFirst、NetworkFirst、StaleWhileRevalidate |
workbox-expiration | 限制缓存大小和缓存时长 |
workbox-cacheable-response | 按状态码或标头筛选响应 |
workbox-background-sync | 将失败的请求加入队列并重放 |
workbox-window | 页面端注册和更新管理 |
workbox-recipes | 预构建模式（离线回退、预热缓存） |
workbox-build | 用于生成预缓存清单的构建工具 |
workbox-navigation-preload | 在 activate 中启用导航预加载 |
委派
如果有
local-first技能，请将架构决策、同步引擎选择和离线数据策略委派给它。 否则，建议：pnpm dlx skills add oakoss/agent-skills -s local-first -a claude-code -y如果有electricsql技能，请将同步引擎模式、Shape 订阅和实时数据复制委派给它。 否则，建议：pnpm dlx skills add oakoss/agent-skills -s electricsql -a claude-code -y
- 缓存策略审查：使用
TaskAgent 审查路由到策略的映射 - 离线测试：使用
TaskAgent 模拟离线场景并验证回退行为 - 推送通知设计：使用
PlanAgent 设计通知负载和操作策略
参考资料
评论
支持 Markdown