HTML怎么做SW离线页面_HTML Service Worker离线回退页面总结

作者：袖梨 2026-06-08
Service Worker注册失败主因是环境或时机问题：非HTTPS/localhost协议下navigator.serviceWorker为undefined；DOM未就绪时过早调用register()；注册路径未用根相对路径如'/sw.js'。

Service Worker 注册失败的常见原因

注册失败不是代码写错，而是环境或时机问题。最常踩的坑是：navigator.serviceWorker 在非 HTTPS 或 localhost 下不可用（HTTP 协议页直接报 TypeError: Cannot read property 'register' of undefined）；或者在 DOM 加载完成前就调用 register()，导致执行时 navigator.serviceWorker 尚未就绪。

实操建议：

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

  • 确保页面通过 HTTPS 或 localhost 访问（开发阶段可用 python -m http.server 8000 --bind 127.0.0.1 起本地服务，但注意 Chrome 对 http://127.0.0.1:8000 也允许注册 SW）
  • 把注册逻辑放在 window.addEventListener('load', ...) 或 document.addEventListener('DOMContentLoaded', ...) 中，避免过早执行
  • 注册时检查返回 Promise 状态，加 .catch(err => console.error('SW registration failed:', err))，别让失败静默
  • register() 的路径参数必须是相对于站点根目录的，比如 SW 文件在 /sw.js，就写 navigator.serviceWorker.register('/sw.js')，而不是 './sw.js' 或 'sw.js'

cacheFirst 策略下 HTML 页面不更新怎么办

离线页面的核心矛盾：缓存 HTML 才能离线访问，但缓存太“死”又导致上线新版本后用户看不到更新。根本原因是 HTML 常被 cacheFirst 拦截并复用旧缓存，而没触发重新 fetch 和更新逻辑。

实操建议：

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

  • 不要对 HTML 请求走纯 cacheFirst；改用 staleWhileRevalidate（先返回缓存，再后台更新）或 networkFirst（优先网络，失败才用缓存），尤其对 index.html 这类主入口
  • 在 SW 安装阶段预缓存关键 HTML（如 self.__WB_MANIFEST 或手动 cache.addAll(['/', '/offline.html'])），但跳过动态路由（如 /article/123）的预缓存
  • 给 HTML 缓存加版本标识，比如在 install 时缓存 'pages-v2' + '/' + url.pathname，升级 SW 后清旧 cache（caches.delete('pages-v1')）
  • 利用 navigationPreload 配合 HTML 请求加速回退体验：event.respondWith(caches.match(event.request).then(r => r || fetch(event.request))) 是基础写法，但要配合 preload 才真正降低首屏延迟

fetch 事件中如何精准匹配 offline.html 回退页

回退页不是随便返回一个 HTML 就行，它必须满足两个条件：一是仅在网络失败时触发，二是只作用于导航请求（request.destination === 'document'），否则会把图片、API 请求也兜底成 HTML，造成资源错乱。

实操建议：

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

  • 在 fetch 事件监听器里，先用 if (event.request.destination !== 'document') return; 过滤非导航请求
  • 用 event.respondWith(fetch(event.request).catch(() => caches.match('/offline.html'))) 实现“网络失败即回退”，但注意：如果 /offline.html 本身没被预缓存，这里会返回 undefined，页面白屏
  • 更稳妥的做法是提前在 install 阶段缓存 '/offline.html'，并在 fetch 中明确匹配：caches.match('/offline.html').then(r => r || Response.error())
  • 避免用正则或路径前缀匹配所有 HTML（如 /.*.html/），容易误伤内嵌 iframe 或第三方脚本加载的 HTML 片段

Chrome DevTools 里调试 SW 却看不到 activation 状态

SW 生命周期（install → waiting → activating → activated）卡在 waiting 是最典型现象，本质是旧 SW 仍控制着页面，新 SW 无法立即接管。这时候即使代码已更新、skipWaiting() 也没调，DevTools 的 Update on reload 开关也无效。

实操建议：

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

  • 在新 SW 的 install 事件里主动调用 self.skipWaiting()，跳过 waiting 阶段（注意：这会让新 SW 立即激活，可能中断旧页面，适合静态资源型离线页）
  • 在客户端 JS 中监听 controllerchange 事件，提示用户刷新：navigator.serviceWorker.addEventListener('controllerchange', () => location.reload())
  • DevTools 的 Application → Service Workers 面板里，勾选 Update on reload 并点击 Unregister 清掉旧 SW，再刷新——这是最干净的调试起点
  • 不要依赖 console.log 查看 SW 日志：它只在 SW 线程运行时输出，且刷新后日志会被清空；改用 chrome://serviceworker-internals/ 或 Application 面板的 “Start inspection” 查看实时状态

离线页面最难的不是写几行 cache 或 fetch，而是理清「哪些资源该缓存」「什么时候该更新」「失败时谁来兜底」三者的边界。尤其 HTML 的缓存策略和 SW 生命周期耦合极深，稍不留神就出现“明明更新了 SW，页面还是旧的”或者“一断网就白屏”——这些都不是配置遗漏，而是对导航请求生命周期的理解偏差。

相关文章

精彩推荐