Chrome端Native App Install Prompt配置后不生效问题求助

一、先做manifest.json硬性格式校验 #

别只确认文件存在，90%的配置问题出在字段错漏、识别失败：

• 打开页面Chrome DevTools，进入Application-Manifest面板，查看是否有红色报错，核心必填字段不能缺：
  • 必须显式设置"prefer_related_applications": true，漏写该字段Chrome只会触发PWA安装提示，不会唤起原生应用安装逻辑
  • related_applications数组内的安卓应用信息必须完全匹配应用包信息，正确配置示例：

{
  "name": "你的站点名称",
  "short_name": "站点短名",
  "prefer_related_applications": true,
  "related_applications": [
    {
      "platform": "play",
      "id": "你的安卓应用完整包名",
      "url": "你的应用官方下载页地址"
    }
  ],
  "icons": [
    {
      "src": "/icon-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any maskable"
    },
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any maskable"
    }
  ]
}

• 校验manifest的响应头：服务端返回manifest文件时必须带Content-Type: application/manifest+json，多数服务器默认给.json后缀文件返回application/json类型，会导致Chrome无法识别配置
• 校验引入标签：manifest的<link rel="manifest" href="/manifest.json">必须放在页面<head>标签内，rel属性不能写错，href地址不能跨域且返回200状态码
• 图标校验：192px、512px两个尺寸的png图标必须能正常访问，不能损坏、不能返回404

二、校验Chrome触发前置条件 #

安卓Chrome原生安装提示和iOS Smart App Banner触发逻辑完全不同，不要套用iOS配置经验，以下条件缺一不可：

• 站点必须注册可正常运行的Service Worker，且能拦截页面fetch请求：Chrome的beforeinstallprompt事件本身绑定PWA可安装门槛，哪怕你只推原生应用、不推PWA，也必须满足SW注册要求
• 测试前必须清空站点数据：Chrome有内置冷却规则，如果用户之前手动点过安装提示的关闭按钮，至少90天内不会对同一用户自动弹出提示。Browserstack测试时每次启动新会话都要清除Chrome全部缓存、站点数据，不要复用旧会话
• 确认测试设备未安装目标安卓应用：设备已装对应App时，Chrome默认不会弹出安装提示
• 加入调试代码确认事件是否触发，在页面脚本中加入以下代码，查看控制台是否输出日志：

window.addEventListener('beforeinstallprompt', (event) => {
  console.log('原生安装提示事件触发成功', event);
  // 调试阶段不要调用event.preventDefault()，确认事件正常触发后再做自定义拦截逻辑
});

三、Browserstack测试环境特殊排查 #

• 不要选无Google Play服务的模拟实例：Chrome原生安装提示依赖GMS校验应用信息，要选择标注「预装Google Play服务」的真实设备实例，纯模拟器环境无GMS永远不会弹出提示
• 给测试环境的Chrome开放全部权限：三星One UI等定制ROM会默认拦截浏览器的后台弹窗权限，测试时手动给Chrome开弹窗权限、存储权限
• 不要在URL里加测试参数、无痕模式下测试：Chrome在无痕模式、带特殊调试参数的页面下不会触发安装提示

常见踩坑点：很多开发者对照旧文档配置，不知道2020年之后Chrome调整了触发规则，把原生App安装提示和PWA安装门槛做了绑定，缺Service Worker、prefer_related_applications字段没开、manifest响应头类型错误是占比最高的三个故障原因。

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