别等有网了再用:给 vibe 项目加上离线优先与 PWA 能力
断网时你的产品还在吗?清单文件、服务工作线程与本地数据库三件套,四档缓存策略,一张 2.4MB 缓存预算表,发件箱同步与冲突三规则,附虚构漏斗 1000→620→410→260→180。

先把三句话说在前面,免得你读错篇。第一,本篇不讲实时协同编辑——站内已有《别再各改各的了:vibe 项目的实时协同编辑实战》,多人同时改一份文档、光标互相看得见那套去看那篇;本篇讲的是一个人、没网的时候,你的产品还能不能用。第二,本篇不讲把网站打包成原生应用上架应用商店,那是另一条路,需要另一套审核与发布流程;本篇讲的是让网页本身在没网时也能打开、能记、能同步,也就是离线优先与渐进式网页应用。第三,本篇不讲直播——直播恰恰要求一直在线,和离线优先是相反的问题。本篇只讲一件事:给你的 vibe 项目加上离线能力,让用户在信号最差的地方也能把核心的事做完,等有网了再悄悄同步回来。全文用一个贯穿始终的虚构示例把道理讲具体:示例产品是“山间手记”,一款让徒步爱好者记录路线、打卡山头、写几句感受的练手应用;示例用户叫“阿山”,一个周末喜欢爬山的普通上班族;示例里的数字、对话和场景全部是虚构的演练,用来把道理讲具体,不是真实产品和真实事件。最后一节的漏斗数字也是虚构样本,用来算账,不是真实数据。
断网的那一刻,用户才发现你的产品是摆设
阿山在一个周六早上六点出发,爬一座城外的小山。山脚下信号满格,他打开山间手记,查了今天的路线,收藏了三条别人走过的轨迹,写了一句“今天天气好,走慢点”。走到半山腰,信号剩一格,他想打开收藏的路线看下一个岔口往左还是往右,页面转了半天,只剩一个转圈的加载图标。又过十分钟,信号彻底没了,他再点一次,浏览器直接给了他一张白底的离线恐龙页面。那一刻他明白了:这个应用只在有网的时候存在,而他最需要它的时候,恰恰是没有网的时候。
他下山之后没有卸载,也没有写差评,他只是再也没打开过。很多 vibe 项目就是这样死掉的:不是功能不够多,而是核心场景和网络条件撞上了。作者在家里写代码,用的都是稳定的宽带,测试的时候从来不断网;用户却在地铁、电梯、山区、地下停车场、信号死角里用产品。离线不是一个锦上添花的卖点,它是你的产品在真实世界里能不能被信任的分界线。做离线优先,第一步不是学技术,而是先承认一件事:用户的使用环境比你的开发环境恶劣得多,你的产品要按最差的网络来设计,而不是按最好的来设计。
离线优先的意思也很朴素:先保证没网也能用,再考虑有网时能多好。顺序不能反。很多项目是反过来的:先把在线体验做到满分,再想起来补一个离线提示,告诉用户“你断网了,请检查网络”。这句话对用户毫无帮助,他当然知道自己断网了,他需要的是已经下载好的路线、已经写好的笔记、一个能先存下来、等有网再发的按钮。离线优先的产品,断网时界面不应该变脸,不应该弹出一张全屏的错误页,而应该像什么都没发生一样继续工作,只在角落里安静地写一句“已保存到本地,有网后自动同步”。
先想清楚:什么必须离线可用,什么可以等
不是所有东西都要离线。把全部功能都做成离线可用,是一个会把你拖垮的目标。正确的做法是先画一条线:线的这边是核心流程,没网也必须能走完;线的那边是锦上添花,有网才有,没网可以先藏起来。判断标准只有一个:用户在没网的时候最想干的那一两件事是什么。山间手记的答案很清楚:查看已经收藏的路线、记录当下的打卡和感受。至于看别人的新动态、给别人的路线点赞、下载别人刚上传的照片,这些都可以等。
阿山的产品后来就是按这条线重做的。收藏的路线和轨迹数据,在用户有网打开时就悄悄存到本地;写笔记和打卡,先写进本地数据库,界面上立刻显示“已保存”,同时在后台排队,等网络恢复再上传。点赞和评论按钮在离线时不是消失,而是变灰并写明“联网后发送”,点一下也不会报错,只会加入队列。用户在山上全程没有看到一次报错,没有丢过一句话,回家连上 Wi-Fi,打开应用看一眼,三条打卡都已经同步上去了,旁边还写着同步成功的时间。这种体验用户说不出来哪里好,但他下次爬山还会打开。
这条线每个产品都不一样。记账应用的核心是记一笔账,离线必须能记;菜谱应用的核心是做饭时能看步骤,离线必须能看已经打开过的菜谱;打卡应用的核心是打卡本身,离线必须能打。反过来,搜索全站内容、拉取实时排行榜、在线支付,这些天生依赖网络的功能,离线时给一个体面的提示就够了,不必硬做。动手之前,先把你的核心流程写下来,只写三条,然后问自己:这三条里,哪一条断网就断了?先修那一条。
三件套:清单文件、服务工作线程与本地数据库
离线优先的技术骨架只有三件套,缺一不可,但每一件的职责要分清。第一件是应用清单文件,也就是 manifest,它是一份 JSON,告诉浏览器你的应用叫什么名字、用什么图标、打开时是什么颜色、是全屏还是带浏览器框。没有它,浏览器不知道你的网页可以被“安装”到主屏幕,用户每次都要先打开浏览器再输入网址。有了它,用户才能把你的应用像一个真正的应用一样留在手机上,一点就开。
第二件是服务工作线程,也就是 service worker。它是一个跑在网页背后的脚本,拦截应用发出的网络请求,决定哪些直接放行去网上取,哪些从本地缓存里拿,哪些先记下来等有网再发。它是离线能力的总开关:没有它,断网时浏览器只能显示错误页;有了它,断网时应用还能从缓存里把页面和数据恢复出来。要注意的是,服务工作线程只能在 HTTPS 下工作,本地开发时 localhost 例外;这意味着你的 vibe 项目如果还跑在纯 HTTP 的临时地址上,离线功能连测试都测不了,先把 HTTPS 解决掉。
第三件是本地数据库,一般用 IndexedDB。它是浏览器里真正能装数据的仓库,容量比 localStorage 大得多,能存结构化的数据:路线、笔记、打卡记录、待同步的队列。localStorage 只适合存几个开关和字符串,路线数据、图片、几百条笔记塞进去很快就会出问题。分工记住一句话:缓存放“长得像文件”的东西,比如页面、脚本、样式和图片;数据库放“长得像记录”的东西,比如用户写的内容和待办的操作。两件东西混着用,是最常见的初学者错误。
这三件套都不需要你从零手写。Workbox 是 Chrome 团队维护的一组工具,专门帮你写服务工作线程里的缓存逻辑,现成的策略拿来就能用;MDN 的渐进式网页应用文档把清单文件、安装条件和离线机制讲得很全;web.dev 的 Learn PWA 是一套循序渐进的教程。你的工作不是发明轮子,而是把这三件套按你产品的核心流程拼起来,并且在真机上断网测一遍。
缓存策略四档:别把所有东西都用同一种办法
服务工作线程里最容易犯的错,是对所有请求用同一种缓存办法,结果要么是用户永远看到旧内容,要么是离线时什么都拿不到。正确的做法是按资源分四档,每一档一种策略。第一档是应用外壳,也就是 HTML、CSS 和 JavaScript 主文件,用“缓存优先”:先从缓存拿,拿不到再去网上取。这样断网时应用至少能打开,界面是完整的。第二档是用户自己的数据,比如已经收藏的路线和已经写好的笔记,用“网络优先,缓存兜底”:有网时先取最新的,失败了再用缓存里的上一份;这样用户既不会看到过期太久的数据,断网时也不会两手空空。
第三档是不常变、体积又大的东西,比如路线封面图和头像,用“过期再验证”:先给缓存里的,背后悄悄去网上看有没有新版,有就换掉,下次打开就是新的。用户感觉不到等待,内容也不会一直旧下去。第四档是绝对不能缓存的东西:登录状态、支付结果、实时余票、别人的私信,这些必须每次都走网络,缓存了反而会出大事——用户可能看到别人的订单,或者以为已经付款成功。给每一种资源定策略之前,先问一句:这东西过期了会出多大的事?过期无非是旧一点,就大胆缓存;过期会误导人、会丢钱,就坚决不缓存。
还有一个细节:缓存要有版本号,也要有上限。每次发布新版本,给缓存起一个新名字,旧缓存由新版的服务工作线程删掉,否则用户可能永远停在上一个版本,你修的 bug 他永远看不到。阿山第一次就踩了这个坑:他修好了路线页面的一处错字,自己手机上还是旧版,查了半天才发现是旧缓存没清。从那以后,他给每次发布都配一个版本号,服务工作线程激活时先删旧缓存再接管页面。另外,图片缓存要设上限,比如只留最近打开过的五十张,超出就删最久没用的,否则用户的手机存储会被你的应用悄悄吃光。
一张缓存预算表:离线不是无限量免费的
离线存储不是无限的。浏览器会给每个网站一个配额,超了就可能被清理,而且手机存储紧张时,浏览器会优先清理那些很久没打开的网站。所以上线之前,先给你的应用算一笔账,写一张缓存预算表。山间手记的预算表是这样的:应用外壳 HTML 是 180KB,主 JavaScript 是 420KB,样式与字体是 160KB,图标一组是 240KB,路线文字数据是 600KB,路线封面缩略图是 800KB。把这六项加起来:180 加 420 是 600,再加 160 是 760,再加 240 是 1000,再加 600 是 1600,再加 800 是 2400KB,也就是 2.4MB。预算表一共 2.4MB,团队给自己定的上限是 5MB,留出一倍的余量给未来加的功能和用户多收藏的路线。
这张表的意义不在于数字本身,而在于它逼你做取舍。缩略图 800KB 是最大的一块,如果想把预算压下来,第一件事就是把封面图压成小尺寸的缩略图,而不是把原图直接缓存;路线文字数据 600KB,如果按每条路线平均 30KB 算,大约能存 20 条路线,超出就按最近打开的时间轮换。反过来,如果不做这张表,缓存很容易在不知不觉中膨胀到十几 MB,用户在手机设置里一看,你的应用占了几百 MB,第一个被删的就是你。预算表应该写进你的发布检查清单,每次加新功能之前,先看一眼还剩多少额度。
还有一点容易被忽略:缓存的东西和数据库里的东西是两笔账。上面的 2.4MB 只是缓存的账,数据库里用户的笔记和待同步队列是另一笔账。笔记是纯文字,一条几 KB,几百条也不过几 MB;照片原图才是大头,一张手机照片三五 MB,十张就几十 MB。所以山间手记定了一条规矩:离线时拍的照片先存缩略图在本地,原图等有 Wi-Fi 再传;用户在设置里能看到本地占了多少空间,也能一键清理已同步的照片原图。把选择权交给用户,比偷偷占满他的手机体面得多。
写操作离线:先存下来,再谈同步
读操作离线相对容易,写操作离线才是真正的考验。用户在没网时写了一段话、改了一个标题、删了一条记录,这些操作不能等网络,必须立刻在本地生效,并且在恢复网络后可靠地同步上去。标准做法是“发件箱”模式:用户的每一次写操作,先写进本地数据库,同时往一个待同步队列里追加一条记录,界面上立刻显示结果。等网络恢复,服务工作线程或者页面里的同步逻辑按顺序把队列里的操作一条一条发给服务器,成功一条删一条,失败的留下来重试。
队列的顺序很重要。阿山的一条打卡,先是创建,再是改了一句话,最后又补了一张照片,这三条操作必须按顺序同步,如果改的那条先到了服务器、创建的那条还在路上,服务器会收到一条针对不存在记录的修改,直接报错。还有重试的次数:不要无限重试,一次失败隔几秒再试,试三次还失败就停下来,告诉用户“有一条记录没同步上去,点一下重试”,而不是在后台默默地烧掉用户的流量和电量。用户能接受一次失败,他不能接受的是不知道自己丢了东西。
冲突是同步里最难的一节,值得单独想清楚。最常见的是同一条笔记在两台设备上都被改了:手机上没网时改了一句,电脑上有网时又改了一句,同步时服务器要决定留哪一句。有三条路可以选。第一条是“后写覆盖先写”,简单粗暴,适合打卡、点赞这种丢了也不心疼的操作。第二条是“字段级合并”,比如标题和正文分开比,谁改了哪个字段就留谁的,适合结构清晰的记录。第三条是“留给用户选”,把两个版本都摆出来,让用户自己挑,适合笔记、日记这种丢一句都心疼的内容。山间手记选的是第三条:冲突时不悄悄覆盖,而是在笔记下面出现一行提示,点开能看到两个版本,选一个或者手动合并。规则可以简单,但必须提前定好,并且写在产品里,而不是等冲突发生了再临时想办法。
安装体验:别在用户第一次打开时就求他安装
能安装到主屏幕,是渐进式网页应用最像原生应用的一点,但安装提示的时机很有讲究。浏览器会在满足条件时触发安装事件:有清单文件、有服务工作线程、有图标、通过 HTTPS 访问。但这不意味着你要在用户第一次打开页面时就弹一个大横幅喊“安装我们的应用”。用户第一次来,连你的产品是干什么的都还不知道,这时候求安装,只会让他点关闭,而且很多浏览器会记住这次拒绝,很久不再给机会。
正确的做法是等用户有了“留下来”的理由再提。山间手记的做法是:用户第二次打开,并且收藏过一条路线之后,才在页面底部出现一条小提示,“把山间手记装到主屏幕,山上没网也能看路线”,附一个“安装”按钮和一个“不用了”的关闭。点安装的就走浏览器的安装流程,点关闭的就一个月内不再打扰。这个时机的选择是有道理的:收藏过路线,说明他真的需要这个产品;第二次打开,说明他不是路过。安装转化率不是靠弹窗的面积堆出来的,是靠用户已经感受到价值之后的一次顺水推舟。
另外要提醒一句苹果手机上的现实:iPhone 的 Safari 对渐进式网页应用的支持和安卓不一样,安装要走浏览器的分享菜单,推送通知等能力也有自己的限制。你的产品如果有很多 iPhone 用户,离线核心功能仍然能用,但不要假设安装流程和安卓完全一样。上线前一定要在真 iPhone 上走一遍:从 Safari 打开、加到主屏幕、断网打开、写一条笔记、恢复网络看同步。模拟器里通过的流程,真机上未必通过;真机上通过一次,比在文档里读十遍都有用。
一串虚构的漏斗:离线做得好不好,看这五步
离线功能上线后,怎么知道它真的有用?只看安装量是不够的,安装了不用,等于没装。山间手记的团队用了一个五步漏斗来衡量,数字是虚构样本,用来演示怎么算账。假设有 1000 次访问:其中 620 人在 7 天内第二次打开,占 62.0%;这 620 人里有 410 人把应用装到了主屏幕,占 66.1%;这 410 人里有 260 人至少用过一次离线功能,占 63.4%;这 260 人里有 180 人在恢复网络后成功同步了离线时写的内容,占 69.2%。整体算下来,1000 次访问里有 180 人走完了从访问到离线使用再到成功同步的全程,整体转化率是 18.0%。流失也对得上:第一步后离开 380 人,第二步后离开 210 人,第三步后离开 150 人,第四步后离开 80 人,最后剩下 180 人,380 加 210 加 150 加 80 再加 180 正好是 1000。
看漏斗要看的是哪一步掉得最狠,而不是只看最后的总数。如果第二步掉得多,说明用户装了却没在没网时打开,可能是他们根本不知道离线能用,你要在界面上把离线状态说清楚;如果第四步掉得多,说明同步总失败,问题在队列和重试逻辑上,而不是在宣传上。山间手记第一次跑这个漏斗,掉得最狠的是第三步到第四步:很多人离线写了东西,但同步失败,查下来是因为照片原图太大,在弱网下反复超时。后来改成先同步文字、照片等 Wi-Fi 再传,第四步的比例立刻上来了。漏斗的价值就在这里:它不告诉你产品好不好,它告诉你下一个星期该修哪一步。

上线前的检查清单:断网测一遍再发布
离线功能最怕的是“在我电脑上能用”。发布之前,按这张清单在真机上走一遍。第一,打开浏览器的开发者工具,把网络调成离线,刷新页面,应用还能不能打开,核心页面是不是都在;第二,在离线状态下走一遍核心流程,写一条内容,改一个标题,退出再进来,内容还在不在;第三,恢复网络,看同步是不是自己发生了,同步失败时有没有提示;第四,更新一次版本,看旧缓存有没有被清掉,用户拿到的是不是新版;第五,换一台很久没打开过这款应用的手机,看存储会不会被浏览器清理,清理之后应用会不会优雅地重新下载而不是直接报错。
还有几处常见的坑。第一个坑是服务工作线程缓存了它自己:如果你的构建流程把服务工作线程文件也当成普通资源缓存起来,新版本可能永远装不上,记得让它每次都走网络。第二个坑是只在 Wi-Fi 下测试:弱网比断网更常见,请求 hang 住半天比直接失败更折磨人,给网络请求设一个超时时间,超时就用缓存顶上。第三个坑是把离线状态藏起来:用户不知道自己离线,就不知道为什么新内容刷不出来,在界面角落放一个小小的离线标记,写清楚“离线中,已保存本地”,能省掉一大半的用户困惑。第四个坑是只测安卓不测 iPhone,上面已经提过,不再重复。
先做一个最小的离线闭环
如果你现在就想动手,不要一上来就做全套。先做一个最小的离线闭环:挑一条核心流程,让它在断网时能走完,恢复网络后能同步回来。山间手记的第一版离线闭环只有三件事:收藏的路线能离线看,写一条打卡能离线存,回家连上网能自动同步。就这三件事,花了一个周末,跑通之后再慢慢加安装提示、图片缓存、冲突处理。离线优先不是一个一次到位的大工程,它是一个可以一小步一小步加的能力,每加一步,用户在没网的时候就多一分信任。
最后回到阿山。后来他再去爬山,半山腰没信号,他打开山间手记,收藏的路线直接在那里,岔口往左的提示清清楚楚,他在山顶写了一句“云海很好,值得早起”,按下保存,界面写着“已保存到本地”。回家连上 Wi-Fi,打开应用,那句话已经同步上去了。他没有给这个应用写过好评,他只是每个周末都打开它。对一个 vibe 项目来说,这就是离线优先能给你的最好回报:用户在最需要你的时候,你在场。
评论 (0)
原始来源
相关文章
同一个页面要在手机、平板、电脑上都站得住。本文按 MDN 的《Responsive web design》《Using media queries》《viewport meta 参考》三篇官方文档讲清楚:流式 HTML、viewport 标签、流式网格与 max-width、图片不撑破容器、媒体查询语法、按内容定断点、mobile-first、响应式字号、按能力查设备与上线检查清单。
localStorage 只能存字符串、没有索引。IndexedDB 是浏览器里真正的数据库:能存结构化数据、容量大得多、能建索引、能用事务。本文按 MDN 的《Using IndexedDB》《IDBDatabase》《IDBObjectStore》三篇官方文档讲清楚:五步套路、开库、升级、主键、索引、事务、add 与 put、get、游标、范围与多标签页升级。
函数你每天都在调,这篇把你一直在做的事讲清楚。本文按 MDN 的《Functions》《Arrow function expressions》《Rest parameters》三篇官方文档讲清楚:声明与表达式、参数与实参、默认值、剩余参数、展开语法、返回值、箭头函数省写规则、this 的坑、回调与高阶函数、作用域。