Angular项目转PWA后桌面快捷方式启动白屏问题求助

问题背景 #

• 为Angular新手，该项目是首个Angular项目，需求为将普通Angular项目转换为PWA应用
• 初始执行ng add @angular/pwa命令时抛出schematic/utility报错，改用ng add @angular/pwa13命令后执行成功
• 完成生产构建、将构建产物上传部署到服务器后，浏览器访问站点可正常展示install安装按钮，点击安装后，弹窗形式的PWA窗口可正常加载对应URL页面
• 异常现象：通过「添加到主屏幕」生成的桌面快捷方式启动PWA时，页面完全空白无内容；重新通过浏览器访问对应URL时，页面会展示open打开应用选项，点击跳转至弹窗形式PWA窗口后页面可正常显示，无法定位异常原因

现有配置 #

manifest 配置 #

{
  "name": "admin",
  "short_name": "admin",
  "theme_color": "#1976d2",
  "background_color": "#fafafa",
  "display": "standalone",
  "scope": "./",
  "start_url": "./",
  "icons": [
    {
      "src": "assets/icons/icon-72x72.png",
      "sizes": "72x72",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "assets/icons/icon-96x96.png",
      "sizes": "96x96",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "assets/icons/icon-128x128.png",
      "sizes": "128x128",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "assets/icons/icon-144x144.png",
      "sizes": "144x144",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "assets/icons/icon-152x152.png",
      "sizes": "152x152",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "assets/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "assets/icons/icon-384x384.png",
      "sizes": "384x384",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "assets/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable any"
    }
  ]
}

ngsw.config 配置 #

{
  "$schema": "./node_modules/@angular/service-worker/config/schema.json",
  "index": "/index.html",
  "assetGroups": [
    {
      "name": "app",
      "installMode": "prefetch",
      "resources": {
        "files": [
          "/favicon.ico",
          "/index.html",
          "/manifest.webmanifest",
          "/*.css",
          "/*.js"
        ]
      }
    },
    {
      "name": "assets",
      "installMode": "lazy",
      "updateMode": "prefetch",
      "resources": {
        "files": [
          "/assets/**",
          "/*.(svg|cur|jpg|jpeg|png|apng|webp|avif|gif|otf|ttf|woff|woff2)"
        ]
      }
    }
  ]
}

排查修复方案 #

核心问题原因 #

manifest中使用相对路径./配置scope和start_url，桌面快捷方式启动时路径解析逻辑和浏览器内直接访问存在差异，导致Service Worker无法正确匹配缓存资源、Angular路由无法命中对应规则，最终触发白屏。

修复步骤 #

1. 修正manifest路径配置
   如果项目部署在站点根目录，将原配置中的相对路径替换为绝对根路径：

"scope": "/",
"start_url": "/",

若项目部署在子路径下（例如访问地址为https://domain.com/admin/），则将上述路径替换为对应子路径，结尾必须保留斜杠，即"scope": "/admin/", "start_url": "/admin/"
如果项目路由使用Hash模式（URL带#），start_url需要配置为"/#/"，避免启动时请求不存在的静态资源。

2. 校验PWA包版本匹配
   确认安装的@angular/pwa版本和本地Angular框架大版本完全一致，跨大版本安装（比如Angular14项目安装@angular/pwa13）会导致Service Worker注册、缓存逻辑异常，建议卸载不匹配版本后重新安装对应版本的包。
3. 调整ngsw-config资源匹配规则
   在app资源组的文件匹配规则中补充层级JS、CSS资源匹配，避免构建分包后的资源无法被Service Worker预缓存：

"files": [
  "/favicon.ico",
  "/index.html",
  "/manifest.webmanifest",
  "/*.css",
  "/*.js",
  "/**/*.css",
  "/**/*.js"
]

4. 重新部署验证

• 执行ng build --prod生成新的生产构建产物
• 全量覆盖服务器上的旧构建文件，不要增量上传避免旧文件残留
• 卸载浏览器中之前安装的旧PWA应用，清除对应站点的所有缓存、Service Worker注册记录
• 重新访问站点触发安装，添加到主屏幕后测试桌面快捷方式启动即可正常加载。

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