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，造成资源错乱。
将 Markdown 文章转换为微信公众号兼容的纯 HTML 格式。当用户要求"转成微信格式"、"生成公众号文章 HTML"、"排版到微信草稿箱"、"微信粘贴格式"时触发。输出带内联样式的纯 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，页面还是旧的”或者“一断网就白屏”——这些都不是配置遗漏，而是对导航请求生命周期的理解偏差。
