PWA核心在于Service Worker可靠接管请求、匹配场景的缓存策略及健壮的安装/更新逻辑。注册需在load事件中同步执行，缓存按资源类型选策略并带版本号，manifest关键字段缺一不可，更新需skipWaiting+controllerchange监听+手动清理旧缓存。

JavaScript PWA 不是靠“加个 manifest 就完事”，核心在于 Service Worker 能否可靠接管网络请求、缓存策略是否匹配实际场景、以及安装/更新逻辑是否健壮。很多项目卡在“能装但不离线”或“更新了但界面没变”，问题几乎都出在生命周期监听和缓存版本管理上。

如何注册并激活 Service Worker

注册必须在页面加载早期执行，且仅支持 HTTPS（localhost 除外）。不能放在模块脚本里异步调用，否则可能被跳过。

• navigator.serviceWorker.register() 必须在 window.addEventListener('load', ...) 或顶层同步脚本中调用
• 注册后立即返回 Promise<serviceworkerregistration></serviceworkerregistration>，但 waiting 或 active 状态需监听 controllerchange 和 statechange 事件才能感知
• 常见错误：在 React/Vue 的 useEffect/onMounted 中注册 → 可能因 hydration 延迟导致注册失败或被忽略
• 推荐写法：

  if ('serviceWorker' in navigator) {
    window.addEventListener('load', () => {
      navigator.serviceWorker.register('/sw.js')
        .catch(err => console.error('SW registration failed:', err));
    });
  }

缓存策略怎么选：Cache API vs. Stale-While-Revalidate

静态资源（HTML/CSS/JS）适合 Cache First，API 数据则要区分：用户关键数据用 Network First，非关键列表页可用 Stale-While-Revalidate。

• caches.open('v1') 的缓存名带版本号，更新 SW 时需手动切换（如改 v2），否则旧缓存不会自动清除
• 不要在 install 事件里 cache.addAll(['/', '/index.html']) —— 这会导致首次访问白屏，因为 HTML 本身还没生成
• 正确做法：在 fetch 事件中对 HTML 请求走 Network First，再用 cache.put() 存储响应；对 /static/ 下资源走 Cache First
• 示例判断逻辑：

  const url = new URL(event.request.url);
  if (url.origin === location.origin && url.pathname === '/') {
    event.respondWith(fetch(event.request).then(r => {
      caches.open('pages-v1').then(cache => cache.put(event.request, r.clone()));
      return r;
    }));
  }

manifest.json 配置哪些字段真正影响安装和桌面图标

浏览器只认 short_name、name、icons、start_url 和 display: 'standalone' 这几个字段。其他如 background_color 只影响启动屏，不决定能否安装。

javascript-typescript-typescript-scaffold

你是 TypeScript 项目架构专家，专注于脚手架搭建生产就绪的 Node.js 和前端应用。生成包含现代工具链（pnpm、Vite、Next.js）、类型

下载

立即学习“Java免费学习笔记（深入）”；

• icons 数组必须包含至少一个 192x192 和一个 512x512 PNG，格式为 image/png，不能是 SVG 或 WebP
• start_url 必须可访问且返回 200，相对路径会被解析为相对于 manifest 文件位置，不是当前页面
• display: 'minimal-ui' 仍显示地址栏，'standalone' 才真正隐藏浏览器 UI；iOS Safari 只支持 'standalone' 和 'fullscreen'
• Chrome 安装提示触发条件：站点满足 30 天内访问 ≥2 次、有 https、有合法 manifest.json、已注册 SW、且用户与页面有交互（如点击）

为什么更新了 SW 却没生效？检查这三点

SW 更新不是发布新文件就立刻切换，它有一套明确的生命周期控制，多数“没更新”是因为没触发 skipWaiting() 或没处理 controllerchange。

• 新 SW 默认处于 waiting 状态，直到所有旧页面关闭 —— 用 self.skipWaiting() 在 install 事件中主动跳过等待
• 页面 JS 仍使用旧 SW 的 controller，需监听 navigator.serviceWorker.addEventListener('controllerchange', ...) 并刷新页面或重载关键模块
• 调试时别只看 DevTools → Application → Service Workers 页面的 “Update on reload”，这个勾选只影响手动刷新行为，不影响生产环境自动更新逻辑
• 验证是否生效：打开 DevTools → Application → Service Workers，看 “Current” 列是否指向新版本；再禁用网络，刷新页面看资源是否从 cache 加载

最常被忽略的是缓存清理时机 —— 新 SW 激活后，旧缓存不会自动删除，得在 activate 事件里手动 caches.delete('old-cache-name')，否则多个版本缓存共存，后续请求可能命中过期资源。