为什么我的PWA在移动端没有显示“添加到主屏幕”提示？

你这个问题我太熟悉了，之前也踩过这个坑，PWA 的「添加到主屏幕」提示在移动端不弹，大概率不是 manifest 或 service worker 注册的问题，而是触发条件没满足全。

先说结论：Chrome 在移动端不会自动弹出 A2HS（Add to Home Screen）提示，除非满足所有触发条件，而且必须由用户主动触发（比如点击按钮） 才能调用安装接口（除了少数情况），你看到的开发者工具里显示 installable，只是说明你满足了「可安装」的静态条件，但离真正弹出安装提示还差一步。

具体来说，Chrome 的自动弹出提示机制在 Android 上有这些硬性要求：

- 必须是 HTTPS（你应该是满足的，不然也注册不了 service worker）
- manifest 必须合法，包含 name、short_name、icons（至少 192 和 512 的）、start_url、display（standalone 是对的）
- service worker 必须正确注册，并且有 fetch 事件监听（哪怕空实现也得有）
- 页面必须通过 service worker 成功缓存至少一次（即 sw 的 install 事件里有 cache.open + cache.addAll 成功）
- 用户必须在你的站点停留过足够久（通常 2 分钟以上），且至少访问过两次（不同会话）
- 最关键的一点：Chrome 在 Android 上从 68 版本开始，已经不再自动弹出 A2HS 提示了，官方明确说这是为了防止滥用，现在必须通过代码显式调用 beforeinstallprompt 事件 + prompt() 来触发安装。

你现在的 manifest 里缺了 icons 字段，这个是硬性要求，没 icons 根本不会被判定为可安装，虽然 devtools 可能会显示 installable（因为 manifest 解析没报错），但实际安装条件不满足。

我给你一个最简但完整的 manifest 示例，注意 icons 必须有，而且分辨率要够（192 和 512 是底线）：

{

  "name": "MyApp",

  "short_name": "App",

  "start_url": "/index.html",

  "display": "standalone",

  "background_color": "#ffffff",

  "theme_color": "#ffffff",

  "icons": [

    {

      "src": "/icons/icon-192x192.png",

      "sizes": "192x192",

      "type": "image/png"

    },

    {

      "src": "/icons/icon-512x512.png",

      "sizes": "512x512",

      "type": "image/png"

    }

  ]

}

service worker 也得写全，不能只注册不缓存，比如：

self.addEventListener('install', event => {

  event.waitUntil(

    caches.open('my-app-v1').then(cache => {

      return cache.addAll([

        '/',

        '/index.html',

        '/styles.css',

        '/app.js',

        '/icons/icon-192x192.png',

        '/icons/icon-512x512.png'

      ]);

    })

  );

});



self.addEventListener('fetch', event => {

  // 即使不做缓存策略，也得有这个监听器，否则 Chrome 认为 sw 无效

});

然后重点来了：你需要监听 beforeinstallprompt 事件，自己控制安装弹窗：

let deferredPrompt;



window.addEventListener('beforeinstallprompt', e => {

  // 阻止 Chrome 自动弹出（虽然它现在也不自动弹了）

  e.preventDefault();

  // 保存事件，等用户点击按钮时再触发

  deferredPrompt = e;



  // 这里可以显示一个「安装 App」的按钮 UI，比如：

  const installBtn = document.getElementById('install-btn');

  installBtn.style.display = 'block';

  installBtn.addEventListener('click', async () => {

    if (!deferredPrompt) return;

    // 显示安装提示

    deferredPrompt.prompt();

    // 等待用户选择

    const { outcome } = await deferredPrompt.userChoice;

    // 清理引用

    deferredPrompt = null;

    installBtn.style.display = 'none';

  });

});

HTML 里加个按钮就行：

<button id="install-btn">安装 MyApp</button>

最后提醒几个容易忽略的点：

- manifest 里 start_url 最好用相对路径（比如 /index.html），别用绝对路径带协议，否则可能被 Chrome 当作跨域而忽略
- icons 图片必须是 PNG，且文件不能太大（超过 1MB 可能被忽略）
- service worker 必须用 navigator.serviceWorker.register('/sw.js') 这种方式注册，路径别写错
- 如果你用的是 PWA Builder 或某些脚手架，它可能生成了错误的 manifest（比如 display: browser），记得检查

我之前调试的时候，经常卡在 sw.js 没有 fetch 监听器，Chrome 就不认它为「有效 sw」，manifest 再规范也没用。还有一次是图标用了 SVG，结果 Chrome 不支持，必须 PNG。

你按这个流程检查一遍，99% 能解决。如果还是不行，建议在 Chrome DevTools 的 Application 面板里看「Manifest」和「Service Workers」两个 tab，有没有红字报错，有时候 manifest 解析失败但不会直接抛异常，而是静默忽略。

你这个情况很常见，manifest和SW注册只是基础条件，缺了一个关键东西：触发安装提示的事件监听没加上。

首先确认你的网页满足PWA安装条件：HTTPS、有manifest.json、注册了service worker、页面可离线访问。你提到Chrome开发者工具显示installable，那这些基本是OK的。

但“添加到主屏幕”提示不会自动弹，得等浏览器触发 beforeinstallprompt 事件。你得在代码里捕获它，不然用户根本看不到提示。

加这段代码：

let deferredPrompt;

window.addEventListener('beforeinstallprompt', (e) => {

  e.preventDefault();

  deferredPrompt = e;

  // 这里可以显示一个自定义按钮，比如“添加到主屏”

  showInstallButton(); // 自定义函数

});



// 当用户点击按钮时触发安装

function promptInstall() {

  if (deferredPrompt) {

    deferredPrompt.prompt();

    deferredPrompt.userChoice.then((choiceResult) => {

      if (choiceResult.outcome === 'accepted') {

        console.log('用户接受了安装');

      }

      deferredPrompt = null;

    });

  }

}

另外检查manifest是不是被正确引用。你在HTML里得有：
<link rel="manifest" href="/manifest.json">
路径别写错，记得转义特殊字符。

还有个小坑：有些安卓机厂商定制系统会屏蔽这个提示，比如华为、小米的浏览器。建议用Chrome再测，确保是标准环境。

最后一点，首次访问不会弹，一般是第二次进入才会触发，因为要等资源缓存完成。你可以先清缓存，刷新几次看看。

把这些补上基本就能弹了。