Service Worker 注册失败主因是环境不满足：仅支持HTTPS（localhost除外），作用域越界需显式设置scope，sw.js须可访问且Content-Type正确，注册代码应尽早执行，DevTools需启用“Update on reload”。
Service Worker 注册失败的常见原因
注册不成功，通常不是代码写错了，而是环境没满足。Service Worker 只能在 HTTPS 下运行（localhost 除外），如果你在 http://192.168.x.x 或普通 HTTP 域名下测试，navigator.serviceWorker.register() 会直接拒绝并抛出异常。
另一个高频问题是作用域（scope）越界：默认注册时 scope 是脚本所在路径的父目录，比如你在 /js/sw.js 注册，scope 就是 /js/，它无法控制 / 下的 HTML。解决方法是显式指定：
navigator.serviceWorker.register('/sw.js', { scope: '/' })
- 确保
sw.js文件能被浏览器直接访问（返回 200，Content-Type 是text/javascript） - 注册代码必须放在页面加载完成之后，但不要等
window.onload—— 越早调越好，比如<script></script>放在底部即可 - Chrome DevTools 的 Application → Service Workers 面板里勾选 “Update on reload”，否则改了 sw.js 也不会自动更新
缓存静态资源的最小可行逻辑
离线可用的核心是拦截 fetch 请求并返回缓存内容。别一上来就写复杂策略，先实现“所有 HTML/CSS/JS 都走 cache-first”：
self.addEventListener('install', e => {
e.waitUntil(
caches.open('v1').then(cache =>
cache.addAll([
'/',
'/index.html',
'/style.css',
'/app.js'
])
)
);
});
self.addEventListener('fetch', e => {
e.respondWith(
caches.match(e.request).then(res => res || fetch(e.request))
);
});
注意：caches.match() 默认只匹配 URL，不带 query 参数；如果请求带 ?t=123，即使缓存了 /app.js，也不会命中。需要手动 normalize 请求或配置 ignoreSearch: true。
立即学习“Java免费学习笔记（深入）”；
-
cache.addAll()是原子操作：任一文件 404 或网络失败，整个 install 就失败，worker 不会激活 - HTML 文件建议用
networkFirst策略（先试网络，失败再 fallback 到缓存），否则用户永远看不到更新 - 不要在 install 阶段调用
fetch()，容易触发 CORS 或跨域限制；静态资源尽量列全、提前部署好
fetch 事件中区分页面与 API 请求
离线应用不是把所有请求都塞进缓存。HTML 页面要可离线打开，而 API 接口往往需要真实响应 —— 这时候得靠请求类型判断：
self.addEventListener('fetch', e => {
const url = new URL(e.request.url);
if (e.request.destination === 'document') {
// 页面请求：优先缓存，fallback 到自定义 offline 页面
e.respondWith(
caches.match(e.request).then(r => r || caches.match('/offline.html'))
);
} else if (url.pathname.startsWith('/api/')) {
// API 请求：网络优先，加超时 fallback（需用 Promise.race + AbortController）
e.respondWith(
fetch(e.request).catch(() => caches.match('/api/fallback.json'))
);
}
});
e.request.destination 是关键字段，值可能是 document、script、style、json 等，比靠 Accept 头或后缀更可靠。
- 对 JSON API 做离线 fallback 时，缓存的 fallback 响应必须和真实接口结构一致，否则前端解析会报错
- 不要在 fetch 事件里无条件
fetch(e.request)后再缓存 —— 这样首次加载仍依赖网络，起不到离线效果 - 动态生成的 URL（如带时间戳或 token）建议在
caches.match()前 strip query，或用cacheKey重写逻辑
调试时最常被忽略的三个细节
Service Worker 的生命周期异步且隐蔽，很多问题不是代码错，而是状态没理清：
- 新版本 sw.js 注册后，旧 worker 仍控制着当前页面，除非手动 skipWaiting 或关掉所有标签页再重开
- 调用
caches.delete('v1')不会立刻生效，得等旧 worker 卸载后，新 worker 的 activate 阶段才能清理 —— 所以清缓存要写在activate事件里 -
console.log在 Service Worker 里输出到 “Console” 面板是无效的，得看 “Application → Service Workers → Logs” 或用self.clients.matchAll()主动发消息到页面调试
真正难的不是写几行缓存逻辑，而是理解 install → waiting → activating → activated 这个链条里，每一步谁在控制、谁在等待、谁已失效。随便改一行代码，可能让整个离线流程卡在 waiting 状态不动。
