Lighthouse检测Manifest.json：未注册控制页面及start_url的Service Worker

问题说明 #

配置PWA应用时触发start_url相关检测异常，使用Lighthouse检测返回报错：

Does not register a service worker that controls page and start_url

Service Worker是支撑渐进式网页应用实现离线访问、添加到主屏幕、推送通知等核心PWA特性的基础技术，仅在manifest.json中新增start_url、修改scope字段无法解决该类报错。
当前使用的manifest.json配置如下：

{
  "name": "Heexy",
  "short_name": "Heexy",
  "description": "Heexy is the private and fast search engine without ads!.",
  "lang": "en-US",
  "start_url":"/?start=url",
  "scope": ".",
  "display": "standalone",
  "theme_color": "#03adfc",
  "background_color": "white",
  "icons": [
    {
      "src": "https://cdn.heexy.org/images/logo.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any maskable"
    }
  ]
}

相关报错截图：

排查与修复步骤 #

该报错核心原因是Service Worker未成功注册，或注册后的控制范围未覆盖页面与start_url对应路径，按以下顺序排查修复即可：

• 检查Service Worker注册逻辑
  Service Worker文件默认只能控制其存放路径同级及下级的路由，如果你的sw.js没有放在站点根目录，默认无法控制根路径下的/?start=url地址。
  根路径下的标准注册代码参考：

  if ('serviceWorker' in navigator) {
    window.addEventListener('load', () => {
      navigator.serviceWorker.register('/sw.js')
        .then(reg => console.log('SW注册成功，控制范围：', reg.scope))
        .catch(err => console.log('SW注册失败：', err))
    })
  }
  

  受部署限制无法将SW文件放到根目录时，注册时需手动传入scope参数，同时需要服务端给SW文件配置Service-Worker-Allowed: /响应头，否则自定义scope不生效。
• 修正manifest配置
  当前配置的"scope": "."为相对路径，解析后易与SW实际控制范围不匹配，直接修改为绝对根路径即可：

  "scope": "/",
  "start_url": "/?start=url"
  

  注意start_url必须在SW控制范围内，不可配置跨域地址，不可超出scope覆盖的路径层级。
• 验证SW运行状态
  部署后打开浏览器开发者工具-应用-Service Worker面板，确认：
  • SW状态为已激活、正在运行
  • 面板显示的SW控制范围与manifest中配置的/完全一致
  • 访问start_url对应地址时，网络面板中该文档请求显示来自Service Worker
• 清除缓存重试
  测试前先注销已安装的旧版本SW，清除站点全部存储数据后硬刷新页面，避免旧SW残留导致检测不通过。

内容的提问来源于stack exchange，提问作者Whatery1087