把网页应用装进主屏幕：vibe 项目的 PWA 安装实战

先说结论：让用户把你的网页“装”进口袋，比上架应用商店快得多

很多 vibe 项目都是网页应用：做好了、能访问了，但用户关掉标签页就再也想不起来。应用商店上架要审核、要包体、要年费，对小团队来说太重；PWA（渐进式网页应用）的“添加到主屏幕”是一条更轻的路：用户在浏览器里点一下，你的应用就以独立图标出现在主屏幕上，有启动屏、能全屏打开、离线也能先打开外壳——而你不需要经过任何商店审核。

本指南讲的就是把这条路完整走通：从 manifest 清单、Service Worker，到安装提示的时机、iOS 的特殊处理，再到上线前的测试清单。文中的示例项目与数据均为虚构，仅用于说明做法。先划清一篇的边界：站内此前已有本地优先与离线同步指南，讲的是数据在断网时怎么办；本篇讲的是“可安装性”本身——图标、启动方式、安装提示与更新流程，两者互补但不重复。

三个硬性条件，缺一不可

浏览器判定一个网页“可安装”，通常要求同时满足三个条件：第一，页面通过 HTTPS 提供（本地开发的 localhost 除外）；第二，有一份合法的 Web App Manifest，声明了名字、图标与启动方式；第三，注册了一个 Service Worker，并且它能实际接管页面（哪怕只是一个最小实现）。三个条件缺了任何一个，安装提示都不会出现——很多开发者反复调试提示逻辑却毫无反应，根因往往是这三项里有一项没满足。

排查顺序也有讲究：先在开发者工具的应用面板里看 Manifest 是否被识别、图标是否齐全，再看 Service Worker 是否注册成功且处于激活状态，最后才看安装提示事件有没有触发。反过来从提示逻辑开始查，会浪费大量时间。虚构示例项目“菜谱本”（一款帮用户收藏与整理菜谱的网页应用）就是按这个顺序排查的：先发现图标缺了 512 尺寸，再发现 Service Worker 注册在了错误的 scope 下，两个修好后提示立刻出现。

Manifest：每一项都对应一个用户可见的结果

Manifest 是一份 JSON 文件，浏览器靠它决定你的应用“长什么样、怎么启动”。最容易出错的几项，逐项说清楚。name 是安装后主屏幕下显示的长名，short_name 是空间不足时的短名——两个都要写，短名控制在 12 个字符以内，否则会被截断。icons 至少要提供 192 与 512 两种尺寸，且必须有一张声明为 maskable（可遮罩）用途：Android 会把图标裁成圆形或圆角矩形，普通图标的边角会被切掉，maskable 图标留了安全边距，裁切后才不会缺角。

display 建议用 standalone：打开后不带浏览器地址栏，看起来像独立应用；如果你的应用强依赖浏览器分享、支付跳转等能力，可以先用 minimal-ui 过渡，不要一上来就 standalone 然后发现关键流程断了。start_url 是用户点图标后打开的第一个地址，建议用干净的首页路径，不要带追踪参数——带参数的 start_url 会导致每次启动都被统计成不同页面，还可能让缓存策略误判。scope 决定 Service Worker 能控制的范围，start_url 必须落在 scope 内，否则安装校验会失败。theme_color 与 background_color 分别决定状态栏颜色与启动屏底色，两个颜色与图标主色保持一致，启动时的视觉过渡才不会闪一下白屏。

图标是最常见的翻车点，单列三条检查：第一，图标不能是透明底大面积留白，否则在深色主屏幕上会糊成一团；第二，512 图标必须是真 512 像素，不要拿小图放大充数；第三，换图标后要清缓存验证，浏览器与系统桌面都可能缓存旧图标，看到旧图标不一定是配置错了，可能是缓存没刷新。

Service Worker：最小实现也要做对四件事

Service Worker 是 PWA 的“后台管家”，但它的最小实现并不复杂，关键是做对四件事。第一，预缓存应用外壳：首页、样式、脚本与启动必需的图片，在安装时缓存下来，让应用离线时至少能打开外壳、显示界面骨架，而不是浏览器默认的断网错误页。第二，准备一张离线兜底页：用户在断网时打开应用，看到的是你设计的“当前离线，已缓存的内容仍可查看”页面，而不是冷冰冰的系统报错。

第三，缓存策略要分而治之：静态资源（样式、脚本、图标）用缓存优先，更新时靠版本号切换；业务数据（菜谱列表、用户收藏）用网络优先、缓存兜底，断网时显示上次的数据并标注“离线数据”。把所有请求都用同一种策略，是最常见的性能与新鲜度双输做法。第四，更新流程要可控：新版本 Service Worker 安装后不要悄悄接管正在使用的旧页面，而是等用户下次打开、或在界面上提示“新版本可用，点击刷新”，由用户确认后再切换。悄悄切换会导致用户正在填的表单突然刷新，体验损失远大于“晚一点更新”。

还有一个必须提前想好的问题：旧版本 Service Worker 的清理。每次发版都要确认旧缓存按版本号清理，否则用户手机里会同时躺着三四个版本的缓存，越攒越大。缓存命名带上版本号、激活时删除非当前版本的缓存，这两行逻辑从第一版就要写好，不要等到用户反馈“应用占了 500MB”才补。

安装提示：时机比按钮样式重要十倍

Android Chrome 会在条件满足时触发 beforeinstallprompt 事件，开发者可以捕获它、暂不展示，等到合适的时机再用自己的按钮触发。最忌讳的做法，是用户第一次打开页面就弹安装提示——用户还不知道你的应用是干什么的，凭什么要把它装进主屏幕？拒绝一次之后，浏览器在一段时间内不会再给机会，你就白白浪费了唯一一次系统级提示。

推荐的时机是“用户已经获得价值之后”：虚构的菜谱本是在用户收藏第三道菜、或连续三天回访时，才在界面角落出现“添加到主屏幕”按钮；按钮文案不说“安装应用”，而是说“把菜谱本放到主屏幕，下次一秒打开”——讲的是用户收益，不是技术动作。用户点击后才调用保存下来的提示事件；用户拒绝后，至少冷却 30 天再考虑二次提示，且二次提示必须换一种理由（比如“你已收藏 20 道菜，放到主屏幕更方便”），而不是原样再弹一次。

另外要处理“已经安装”的状态：通过监听 appinstalled 事件，或用 display-mode 媒体查询判断当前是否以 standalone 模式打开，已经安装的用户就不应该再看到安装按钮。给已安装用户继续推安装，是最能暴露“这个产品没人认真用过”的细节。

iOS：没有自动提示，只能教用户手动添加

iOS 是 PWA 安装最特殊的一环：Safari 不支持 beforeinstallprompt 事件，没有系统自动提示，安装只能靠用户手动操作——点分享按钮，再点“添加到主屏幕”。这意味着你在 iOS 上不能等提示，必须主动教用户：准备一张三步引导图（分享 → 添加到主屏幕 → 确认），在用户完成关键行为后展示；引导图要用真实的 iOS 界面样式，不要用 Android 的截图去教 iOS 用户。

iOS 还有几处细节值得单独注意。第一，iOS 对图标与启动屏的处理与 Android 不同，apple-touch-icon 需要单独提供，缺了它主屏幕图标会很难看。第二，iOS 上独立打开的应用与 Safari 的存储并不完全互通，登录态、缓存可能需要用户重新登录——如果你的应用强依赖登录态，要在引导文案里提前说明，避免用户装完发现要重新登录而困惑。第三，不要用“检测到 iOS 就弹全屏遮罩”的粗暴做法，引导应该出现在用户已经认可产品价值之后，且随时可以关闭。

一句话总结 iOS 策略：Android 是“等系统提示、挑好时机”，iOS 是“自己教用户、给一张图”。两套逻辑都要写，缺了任何一套，都会丢掉一半用户。

上线前测试清单：真机、图标、更新，三项都要过

测试清单分三组，每组都必须在真机上过一遍，模拟器只能做初步验证。第一组，安装流程：Android 真机上从未安装状态打开页面，确认提示逻辑按设计触发；iOS 真机上按引导图手动添加，确认图标、名字、启动屏都正确；安装后从主屏幕打开，确认地址栏消失、启动正常。第二组，图标与启动：换深色与浅色壁纸各看一次图标效果，确认 maskable 安全边距生效；冷启动看一次启动屏，确认底色与主题色一致、没有白屏闪烁。

第三组，更新流程：先装旧版本，再发新版本，确认旧页面不会被悄悄刷新、用户能看到“新版本可用”提示、点击后正确切换到新版；断网状态下打开应用，确认外壳与兜底页正常、已缓存内容可查看。任何一组失败，都不要先怀疑浏览器——先回查前面的三项硬性条件与 Manifest 字段，九成问题都在那里。

度量：装了多少、回访有没有变好，才算做完

上线后要度量两件事。第一，安装转化：记录安装按钮展示次数、点击次数、appinstalled 成功次数，算出每一步的转化率；如果展示多、点击少，问题在时机或文案；如果点击多、成功少，问题在安装条件或引导流程。第二，回访变化：对比安装用户与未安装用户的 7 日回访率与使用时长——PWA 安装的价值最终要体现在回访上，而不是“装机数”这个虚荣数字上。

度量时注意口径：用 display-mode 区分 standalone 启动与浏览器启动，不要把两者混在一起算；安装成功事件在 iOS 上无法直接监听，iOS 的安装量只能通过启动来源间接估算，汇报时要说明口径差异，不要把估算数当成精确数。数据口径写进文档，比数据本身好看更重要。

一份 30 分钟的上线演练：从零到主屏幕走一遍

如果前面读下来觉得条目太多，记住这份 30 分钟演练就够了。0–5 分钟：在开发者工具里确认 Manifest 被识别、图标 192 与 512 齐全、Service Worker 已激活。5–15 分钟：Android 真机上走一遍安装流程，从未安装状态打开、等提示出现、完成安装、从主屏幕打开，确认地址栏消失。15–25 分钟：iOS 真机上按引导图手动添加，确认图标与名字正确、登录态表现符合预期。25–30 分钟：发一个新版本，确认旧页面不会被悄悄刷新、用户能看到更新提示。

这 30 分钟的价值在于，它覆盖了用户旅程的每一个关键节点：发现、安装、启动、更新。很多 PWA 问题不是“做不出来”，而是“没人完整走过一遍”——开发者在模拟器里看了 Manifest 就以为做完了，真机上的图标、登录态、更新提示全都没验证。30 分钟换一次完整旅程，是 PWA 上线前性价比最高的投入。

反模式清单：这七件事不要做

最后列七个反模式。第一，首访就弹安装提示，用户还没获得价值就被打扰。第二，图标透明底或小图放大，主屏幕上糊成一团。第三，start_url 带追踪参数，启动统计全乱套。第四，Service Worker 缓存不分策略，静态与数据一锅烩。第五，新版本悄悄接管正在填写的页面，用户表单丢失。第六，旧缓存不清理，应用体积越攒越大。第七，给已安装用户继续推安装按钮，暴露产品没人认真用过。七条全避开，你的 PWA 安装流程就已经超过了大多数 vibe 项目的平均水平——剩下的，就是等用户在主屏幕上每天看到你的图标。

装上之后才是开始：更新、留存与再营销

很多团队把安装成功当成终点，其实安装只是用户关系的起点。先说更新：Service Worker 的更新策略直接决定用户下次打开看到的是新版还是旧版。建议把“新版本可用”的提示做成显性但不打扰的形式，比如在设置页或下次启动时出现一条可关闭的提示，而不是在用户正在填写表单时强制刷新。强制刷新换来的是最新版本，丢掉的却是用户正在输入的内容，这笔账怎么算都不划算。更新提示还要带上版本号和一句话更新说明，让用户知道这次更新值不值得立即重启，而不是面对一条语焉不详的“有新版本”无所适从。

再说留存度量。安装之后要单独看三个数字：安装用户的次日和七日回访率、主屏幕启动占比、以及卸载或移除率。回访率告诉你安装有没有带来真实使用，启动占比告诉你主屏幕入口是不是真的被用起来了，移除率则是最诚实的差评——用户愿意花力气把图标从主屏幕删掉，说明产品在某个环节让他失望了。这三个数字要和未安装用户对照着看，如果安装用户的回访率并没有明显高于网页用户，说明安装流程本身可能只是给“本来就会回来的人”多加了一个入口，而不是真正扩大了用户群。这时候该优化的不是安装提示的文案，而是产品本身值得每天打开的理由。

最后是再营销的边界。装到主屏幕的应用天然适合用通知召回用户，但通知是最容易被滥用的能力。原则是只在用户明确受益的场景发通知：比如他收藏的内容有更新、他发起的任务有了结果、他设置的提醒到了时间。切忌把通知当成群发广告的渠道，一次无关通知换来的可能是永久关闭通知权限，甚至直接卸载。通知权限的申请时机也要讲究：不要在用户第一次打开应用时就弹权限申请，等到他完成了一个值得被提醒的动作、比如收藏了第一道菜或创建了第一个任务时，再说明“开启通知后，这类更新会第一时间告诉你”，通过率会高得多。安装、更新、通知这三件事都做到克制，PWA 才算真正融入了用户的手机，而不是在主屏幕上占了一个格子。

补一句容易被漏掉的检查：上线前务必在真实安卓机和真实苹果机上各走一遍完整流程，模拟器和桌面浏览器只能覆盖一半问题，尤其是苹果侧的手动添加步骤，模拟器里根本测不出来。