安卓Chrome中PWA的Add To Homescreen横幅不显示问题求助

一、先确认基础触发条件 #

安卓Chrome弹出添加横幅有硬性要求，先核对：

• 网站得走HTTPS（本地开发用localhost/127.0.0.1可以例外）
• Service Worker必须注册成功且处于activated状态（不是光注册就行）
• Manifest配置得达标
• 你没手动关过这个网站的横幅提示，而且当前会话没弹出过横幅

二、Manifest.json 逐项检查 #

这些配置一个都不能少：

• name和short_name：必须有，short_name尽量短（12字以内最好）
• start_url：路径要对，建议用相对路径./，别带多余的查询参数，确保从这个URL能正常打开应用
• display：得设成standalone、fullscreen或minimal-ui（不能是browser）
• icons：至少要有192x192px和512x512px的PNG图标，type要设为image/png
• theme_color和background_color：建议加上，有些版本会影响触发

给个正确配置的例子：

{
  "name": "我的PWA应用",
  "short_name": "PWA应用",
  "start_url": "./",
  "display": "standalone",
  "icons": [
    {
      "src": "icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "theme_color": "#2196F3",
  "background_color": "#ffffff"
}

三、Service Worker 排查要点 #

• 先确认sw.js的路径没错，index.js里的注册代码能跑通
• 注册代码最好放在页面加载完成后，比如这么写：

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/sw.js')
      .then(registration => {
        console.log('SW注册成功: ', registration);
      })
      .catch(err => {
        console.log('SW注册失败: ', err);
      });
  });
}

• 去Chrome DevTools的Application > Service Workers面板看状态，得是activated且is running，要是install或activate阶段报错，得先把bug修了
• 别在Service Worker里用只能HTTPS用的API（localhost除外），不然可能激活失败

四、其他调试技巧 #

• 打开Chrome DevTools的Application > Manifest面板，看有没有红色警告，有就挨个修复
• 在Application > Service Workers里勾上Update on reload，强制刷新SW，确保用的是最新版本
• 清除网站缓存和SW：Application > Storage > Clear site data，然后重新加载页面
• 要是你之前点过横幅的“取消”，Chrome会在一段时间内不再弹，调试的话可以开chrome://flags/#bypass-app-banner-engagement-checks绕过这个限制（仅限测试用）
• 确保你的安卓Chrome版本在72以上，旧版本对PWA支持不全

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