HTML怎么做Service Worker注册_HTML Service Worker注册安装实战

作者：袖梨 2026-07-27

Service Worker注册失败主因是环境或时机问题：非HTTPS（localhost除外）、sw.js路径404、注册过早；需确保安全上下文、load后注册、scope覆盖目标路径，并验证sw.js可访问及Content-Type正确。

Service Worker 注册失败，八成不是代码写错了，而是环境或时机没对——HTTPS 缺失、sw.js 路径 404、注册时机过早，这三个问题占了实际报错的 90% 以上。

注册前必须确认 HTTPS 或 localhost

浏览器只允许在安全上下文（secure context）中注册 Service Worker。navigator.serviceWorker.register() 在非 HTTPS 的生产域名（比如 http://example.com）下会直接抛出 SecurityError，连 catch 都捕不到，控制台只显示 “Registration failed: SecurityError”。

开发阶段：仅 http://localhost 和 http://127.0.0.1 被豁免，其他 http 地址（如 http://test.local）一律不工作
生产部署：必须用 HTTPS，哪怕自签名证书也行，但不能是纯 HTTP
验证方法：打开浏览器开发者工具 → Application → Service Workers 标签页，如果灰色不可用，先检查地址栏锁图标

`navigator.serviceWorker.register()` 必须在 load 后执行

注册调用不能放在 <script> 标签里就立刻执行，否则可能因 DOM 尚未就绪或 navigator 对象未完全初始化而静默失败。常见错误是把注册逻辑写在 DOMContentLoaded 之前，或塞进某个异步模块加载回调里却没等页面真正 ready。

正确做法：绑定到 window.addEventListener('load', ...)，确保 HTML、CSS、JS 全部加载完成
不要用 document.addEventListener('DOMContentLoaded', ...) —— 此时 Service Worker 可能还没准备好接管 fetch
若用构建工具（如 Vite/webpack），注意 /sw.js 是否被正确输出到静态目录根路径；访问 https://yoursite.com/sw.js 应返回 JS 文件内容，状态码 200，而非 404

scope 参数不填默认是 /，但路径错会导致注册成功却无效

看起来 navigator.serviceWorker.register('/sw.js') 返回了 Promise resolve，控制台也打印 “registered”，但后续 fetch 事件根本不触发——大概率是 scope 范围没覆盖到你要拦截的页面。

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

默认 scope 是 sw.js 所在路径的父目录，比如 /assets/sw.js 的默认 scope 是 /assets/，它无法拦截根目录下的 /index.html
显式指定 { scope: '/' } 可强制扩大作用域，但前提是 sw.js 文件本身也得在可访问的上级路径（例如放在根目录）
scope 不能越权：你不能把 /sw.js 的 scope 设为 /admin/，也不能把 /scripts/sw.js 的 scope 设为 /（浏览器会拒绝）
注册后可在 DevTools → Application → Service Workers 查看 “Scope” 字段，确认是否符合预期

install 事件不触发？检查 sw.js 的响应头和语法错误

注册成功只是第一步，真正缓存资源靠的是 install 事件。如果控制台没打印 “Installing” 或缓存没生效，问题往往出在 sw.js 文件本身。

服务器必须返回 Content-Type: text/javascript，某些 Nginx/Apache 配置会把无扩展名文件（或 .js 文件）误判为 text/plain，导致 install 不触发
sw.js 里不能有语法错误（哪怕一个逗号错位），整个脚本会加载失败，且错误通常只出现在 DevTools → Console 的 “Service Worker” 分组下，容易被忽略
首次注册时，旧版 SW 若处于 waiting 状态，新版本不会自动激活；加一行 self.skipWaiting() 在 install 里可跳过等待（配合 clients.claim() 在 activate 中使用）
调试技巧：在 sw.js 开头加 console.log('SW loaded')，然后在 DevTools → Application → Service Workers → “Update on reload” 打钩，刷新页面看日志是否出现