Yii2框架PWA实现故障：安装弹窗未触发求助

问题背景 #

基于PHP Yii2框架开发的项目已配置PWA相关文件：

• manifest.json经开发者工具验证配置正常
• service-worker.js已成功注册
• 所有设备均未触发应用安装弹窗

现有配置代码 #

sw.js #

var staticCacheName = 'pwa-v' + new Date().getTime()

var filesToCache = [
        'css/bootstrap.css',
        'css/select2.min.css',
        'css/select2-bootstrap.css',
        'css/anno.css',
        'css/jquery.mThumbnailScroller.css',
        'css/jquery-ui.css',
        'css/bootstrap-theme.css',
        'css/fm.selectator.jquery.css',
        'css/lightgallery.min.css',
        'css/magnific-popup.css',
        'css/jquery.mCustomScrollbar.css',
        'css/bootstrap-datetimepicker.css',
        'css/croppie.css',
        'https://cdnjs.cloudflare.com/ajax/libs/bootstrap-select/1.11.2/css/bootstrap-select.min.css',
        'css/developer.css',
        'css/empwin.css?v=2.37',
    'js/bootstrap.js?v=0.01',
        'js/fm.selectator.jquery.js?v=0.01',
        'js/lightgallery-all.min.js?v=0.01',
        'js/jquery.magnific-popup.min.js?v=0.01',
        'js/jquery.mThumbnailScroller.js?v=0.01',
        'js/moment.js?v=0.01',
        'js/bootstrap-datetimepicker.min.js?v=0.01',
        'js/highlight.min.js?v=0.01',
        'js/jquery-ui.js?v=0.01',
        'js/bootstrap-transition.js?v=0.01',
        'js/jquery.geocomplete.min.js?v=0.01',
        'js/croppie.js?v=0.01',
        'js/webcam.js?v=0.01',
        'js/anchorme.min.js?v=0.01',
        'js/anno.js?v=0.01',
        'https://cdnjs.cloudflare.com/ajax/libs/bootstrap-select/1.11.2/js/bootstrap-select.min.js',
        'https://cdnjs.cloudflare.com/ajax/libs/jquery.lazyload/1.9.1/jquery.lazyload.min.js',
        'js/jquery.ui.core.min.js?v=0.01',
        'js/jquery.ui.timepicker.js?v=0.01',
        'js/jquery.pinBox.min.js?v=0.01',
        'js/propeller.min.js?v=0.01',
        'js/select2.full.js?v=0.01',
        'js/video.js?v=0.01',
        'js/jquery.mCustomScrollbar.concat.min.js?v=0.01',
        'js/custom.js?v=3.49',
        'js/custom1.js?v=0.02',
        'js/blur.js?v=0.01',
        'js/exif.js?v=0.02',
        'js/browser-deeplink.min.js',
]

// Cache on install
self.addEventListener("install", event => {
    this.skipWaiting();
    event.waitUntil(
        caches.open(staticCacheName)
            .then(cache => {
                return cache.addAll(filesToCache);
            })
    )
});

// Clear cache on activate
self.addEventListener('activate', event => {
    event.waitUntil(
        caches.keys().then(cacheNames => {
            return Promise.all(
                cacheNames
                    .filter(cacheName => (cacheName.startsWith("pwa-")))
                    .filter(cacheName => (cacheName !== staticCacheName))
                    .map(cacheName => caches.delete(cacheName))
            );
        })
    );
});

//Serve from Cache
self.addEventListener("fetch", event => {
    event.respondWith(
        caches.match(event.request)
            .then(response => {
                return response || fetch(event.request);
            })
            .catch(() => {
                return caches.match('offline');
            })
    )
});

manifest.json #

{
    "theme_color": "#175795",
    "background_color": "#175795",
    "display": "standalone",
    "orientation": "portrait",
    "scope": "xxx",
    "start_url": "xxx",
    "name": "win",
    "icons": [
    {
      "src": "images/icons/icon-72x72.png",
      "sizes": "72x72",
      "type": "image/png"
    },
    {
      "src": "images/icons/icon-96x96.png",
      "sizes": "96x96",
      "type": "image/png"
    },
    {
      "src": "images/icons/icon-128x128.png",
      "sizes": "128x128",
      "type": "image/png"
    },
    {
      "src": "images/icons/icon-144x144.png",
      "sizes": "144x144",
      "type": "image/png"
    },
    {
      "src": "images/icons/icon-152x152.png",
      "sizes": "152x152",
      "type": "image/png"
    },
    {
      "src": "images/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "images/icons/icon-384x384.png",
      "sizes": "384x384",
      "type": "image/png"
    },
    {
      "src": "images/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

排查与解决步骤 #

1. 确认HTTPS环境
   PWA安装弹窗仅在HTTPS环境（localhost开发环境除外）触发，生产环境必须配置有效SSL证书，避免使用自签证书（部分移动设备不认可）。

2. 修正manifest配置

   • 替换scope和start_url的占位符xxx：start_url需指向可访问的页面，且在scope范围内；若应用是全站范围，scope设为"/"，start_url设为"/"或具体首页地址。
   • 添加short_name字段：部分浏览器要求该字段才会触发安装提示，示例："short_name": "win"。
   • 验证图标可用性：在开发者工具Application > Manifest面板检查所有图标是否加载成功，确保文件路径正确且文件存在。

3. 完善Service Worker逻辑

   • 修复offline页面缺失问题：将offline.html添加到filesToCache列表，并确保该文件存在。
   • 处理缓存失败场景：cache.addAll若有单个资源加载失败会导致整个缓存失败，添加错误捕获避免SW安装异常：

     cache.addAll(filesToCache).catch(err => console.log('缓存资源失败:', err));
     

   • 监听安装提示事件：浏览器不会自动触发弹窗，需用户交互后才会触发，可自定义安装按钮：

     // 页面JS中添加
     let deferredPrompt;
     window.addEventListener('beforeinstallprompt', (e) => {
       e.preventDefault();
       deferredPrompt = e;
       // 显示自定义安装按钮
       document.getElementById('installBtn').style.display = 'block';
     });
     
     // 点击按钮触发安装
     document.getElementById('installBtn').addEventListener('click', () => {
       deferredPrompt.prompt();
       deferredPrompt.userChoice.then(() => {
         deferredPrompt = null;
       });
     });
     

4. 验证浏览器状态

   • 在Chrome开发者工具Application > Manifest面板，查看"Add to Home screen"选项的可用性，若不可用会显示具体失败原因。
   • 检查设备是否已安装该应用：已安装的应用不会再次触发弹窗，卸载后重试。
   • 移动端测试优先：部分桌面浏览器触发条件严格，优先在Android Chrome、iOS Safari（iOS 16.4+支持）测试。

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