web app manifest 文件必须存在且配置正确，关键字段short_name、name、icons、start_url、display缺一不可，需https部署并满足平台特定条件（如ios需两次访问间隔24小时）才能触发“添加到主屏幕”提示。
Web App Manifest 文件必须存在且配置正确
没有有效的 manifest.json，iOS 和 Android 都不会显示“添加到主屏幕”提示。浏览器会直接忽略相关逻辑。
关键字段不能缺失或格式错误：
-
short_name和name都要提供，且short_name长度建议 ≤ 12 字符（iOS 截断严格） -
icons至少包含一个192x192和一个512x512的 PNG 图标，type必须明确写成"image/png" -
start_url必须是相对路径或同源绝对路径（如"/"或"/app/"），不能是带参数的动态 URL（如"/?ref=pwa"） -
display推荐设为"standalone"或"minimal-ui"；设为"browser"会禁用添加行为
页面需通过 HTTPS 提供，且满足“可安装性”指标
Chrome（Android）和 Edge 会检查三项核心指标：HTTPS、注册了 service worker、有合法 manifest.json。缺一不可。
iOS（Safari）不强制要求 service worker，但必须 HTTPS + 有效 manifest + 用户至少访问两次（间隔 ≥ 24 小时）才会触发提示 —— 这个时间阈值无法绕过。
- 本地开发可用
localhost绕过 HTTPS 限制，但部署后必须用真实证书（自签名无效） - 检查是否满足安装条件：在 Chrome DevTools 的
Application > Manifest面板看 “Installability checklist” 是否全绿 - 若提示 “User has not visited site enough”，说明访问频次/停留时间未达标，不是代码问题
手动触发添加引导需监听 beforeinstallprompt 事件
这个事件只在 Chrome/Edge 等支持 PWA 安装的浏览器中触发，且仅一次 —— 如果没保存事件对象，后续无法再唤起安装弹窗。
典型错误是把 event.prompt() 直接写在事件回调里，导致自动触发（违反用户手势要求）或被浏览器拦截。
- 必须在事件触发时调用
event.preventDefault()，然后缓存event到全局变量（如window.deferredPrompt） - 只能在用户明确点击按钮后，再调用
window.deferredPrompt.prompt()，并监听userChoice结果 - iOS Safari 不支持该事件，需单独用
Navigator.standalone或matchMedia("(display-mode: standalone)")检测是否已添加
let deferredPrompt;
window.addEventListener('beforeinstallprompt', (e) => {
e.preventDefault();
deferredPrompt = e;
showInstallButton(); // 自行实现 UI 显示逻辑
});
installBtn.addEventListener('click', () => {
if (deferredPrompt) {
deferredPrompt.prompt();
deferredPrompt.userChoice.then((choice) => {
if (choice.outcome === 'accepted') console.log('Added to home screen');
deferredPrompt = null;
});
}
});
引导文案与时机必须符合平台习惯
硬推“点击添加”按钮大概率被用户忽略或反感。iOS 和 Android 对引导节奏敏感度不同。
- 不要在首屏立即弹浮层；建议等用户完成一次核心操作（如提交表单、看完文章）后再浮现轻量提示
- iOS 用户更依赖原生交互：可在页面底部加一行文字提示“轻点 分享 → 添加到主屏幕”，并配 Safari 截图示意
- Android 用户接受按钮式引导，但文案避免用“App”字眼（可能被浏览器标记为误导），改用“添加到主屏幕”或“离线使用”
- 检测到已添加后（
Navigator.standalone === true或display-mode: standalone），应隐藏所有引导 UI
icons 条目，Safari 就完全不识别 manifest，也不会报错，只会静默失败。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
