看一眼标题熟悉Uniapp这套东西的朋友应该秒懂——这是要把H5打包出来的那个“网页版”硬生生地做成一个能离线用、能缓存、能当半个原生App使的PWA。电商场景下玩Uniapp PWA说穿了就是解决三件事商品数据不能每次打开都从服务器拉一遍、购物车不能因为手滑刷新就清零、支付流程不能走一半卡死在回调里。这篇文章是“Uniapp PWA 场景落地”系列的第二篇上一篇我们把PWA的壳装上了manifest配好、Service Worker注册成功、离线包能缓存页面这一篇完全聚焦电商实战商品缓存怎么做、购物车怎么持久化、支付流程怎么优化。适合谁看正在用Uniapp做多端电商项目、又不甘心H5端只是“能打开但难用”的开发者。老实说这一篇的内容是我在真实电商项目里拆出来的不是拿着文档念PPT每个方案都踩过坑之后才定下来的。1. 项目背景与方案选型为什么电商场景非得用 PWA1.1 Uniapp 三端同构中的 H5 短板PWA 恰好补上了Uniapp 这套框架最大的卖点是“一套代码三端运行”但实际上开发过的人心里都有本账小程序端有微信的天然流量和支付闭环App 端能上原生插件、推送、热更新唯独 H5 端最尴尬。H5 既没有小程序的离线能力也没有 App 的系统权限更麻烦的是用户在浏览器里逛电商网站每一次刷新页面商品列表要从头拉、用户信息要重新鉴权、购物车状态说没就没。我做过一个真实的商城项目小程序端和 App 端都已经上线H5 端一直是个“挂着能看”的状态。用户从短信链接点进来浏览了几个商品加购了几样东西退出去之后再点进来购物车空了。客户反馈说“感觉这个网页版是个摆设”其实不是开发者不努力而是 H5 天然缺了“持久化”和“离线”这两个 App 与小程序与生俱来的能力。PWA 恰好就是来补这两个短板的。PWA 不是一门新语言它是一套浏览器能力的组合拳manifest.json 负责让网页能“添加到主屏幕”Service Worker 负责拦截网络请求、做缓存、控制离线策略Cache Storage 和 IndexedDB 负责存储数据。换句话说PWA 就是给 Uniapp 的 H5 端装上了一个“轻量版的 App 内核”。1.2 三个得力干将离线缓存、桌面入口、断网兜底电商场景里PWA 带来的价值可以拆成三条线来理解。第一条是离线缓存。用户打开过一次商品列表页Service Worker 就把这个页面的 HTML、CSS、JS 以及商品图片都缓存下来了。第二次打开的时候哪怕网络信号弱到只有一格页面也能秒出。这在用户等电梯、过隧道、信号差的场景里体验差距是肉眼可见的。第二条是桌面入口。PWA 配置了 manifest 之后用户在浏览器里点“添加到主屏幕”手机桌面上就多了一个图标点开是独立窗口、全屏显示没有浏览器地址栏。虽然它不像 App 应用商店那样分发但转化路径短了用户留存率确实能提升。有个统计数据一直很稳定被添加到桌面的 PWA次月回访率远高于普通浏览器标签页。第三条是断网兜底。电商场景最怕的是用户下单到一半断网。页面刷新不出来、订单状态不明、购物车读取失败这些在弱网环境下都会让人直接放弃购买。PWA 的 Service Worker 可以在断网时返回缓存的页面框架配合本地持久化的购物车数据至少能保证用户看到的东西是“活的”而不是一个死板的错误页。1.3 整体技术架构与工作目录规划我用 Uniapp 的 Vue3 版本 Vite 构建H5 端打包产物直接部署在 Nginx 静态服务器上。项目目录里单独建了一个pwa文件夹用来放 Service Worker 的注册文件和缓存策略配置。真正落地的时候目录规划比写代码更值得讲究因为后期你会频繁调整缓存策略如果代码散落在业务组件里改起来就是一场灾难。我自己的习惯是这样的├── src │ ├── pages # 业务页面 │ ├── stores # Pinia 状态管理 │ ├── api # 接口封装 │ └── pwa │ ├── sw.js # Service Worker 主文件 │ ├── register.js # SW 注册逻辑 │ └── cache-config.js # 缓存版本与策略配置cache-config.js单独拎出来是刻意的因为缓存策略是电商项目里需要经常调整的部分大促期间要缓存更多商品页、平时要控制缓存体积这个文件就是全项目的“缓存总闸”。2. 商品缓存设计从静态资源缓存到业务数据缓存2.1 先分清缓存对象构建产物和接口数据不能混为一谈很多第一次做 PWA 电商项目的同学会走一个弯路把整个网站所有请求全部交给 Service Worker 缓存结果缓存策略写得粗暴商品价格变了页面还是旧的用户看到一天前的价格自然会怀疑平台在搞什么名堂。正确的做法是把缓存对象分成两类分别制定策略。第一类是静态构建产物打包出来的 JS、CSS、图片、字体。这些文件带有 hash 后缀内容变了文件名就变了所以缓存策略可以非常激进——命中缓存直接返回永不重新请求除非缓存文件本身被清理。这一类交给 Service Worker 的 pre-cache预缓存机制在 SW 安装阶段就把核心资源预先下载好。第二类是接口数据商品详情、列表、价格、库存这些动态内容。这类数据天然就是“要以服务器为准”的但是完全不走缓存又浪费了 PWA 的离线优势。折中方案是 network-first网络优先策略先请求服务器如果成功了就用新数据并更新缓存如果网络失败才用上次缓存的旧数据兜底。这样既保证了数据新鲜度又能在弱网环境兜底。2.2 Service Worker 缓存策略配置实操这里放一段我实际在用、压测过没毛病的核心缓存注册逻辑。基于常见的实践补充一些注释方便大家直接抄。// pwa/sw.js const CACHE_VERSION shop-pwa-v2.1.0 const PRECACHE_ASSETS [ /index.html, /static/js/runtime.js, /static/js/vendor.js, /static/css/app.css, /static/img/logo.png ] self.addEventListener(install, event { event.waitUntil( caches.open(CACHE_VERSION) .then(cache cache.addAll(PRECACHE_ASSETS)) .then(() self.skipWaiting()) ) }) self.addEventListener(activate, event { event.waitUntil( caches.keys().then(cacheNames { return Promise.all( cacheNames .filter(name name ! CACHE_VERSION) .map(name caches.delete(name)) ) }).then(() self.clients.claim()) ) }) self.addEventListener(fetch, event { const requestUrl new URL(event.request.url) // 静态资源cache-first if (requestUrl.origin self.location.origin /\.(js|css|png|jpg|jpeg|svg|woff2)$/.test(requestUrl.pathname)) { event.respondWith( caches.match(event.request).then(cached { return cached || fetch(event.request).then(response { const copy response.clone() caches.open(CACHE_VERSION).then(cache cache.put(event.request, copy)) return response }) }) ) return } // 接口数据network-first if (requestUrl.pathname.startsWith(/api/)) { event.respondWith( fetch(event.request) .then(response { const copy response.clone() caches.open(api-cache-v1).then(cache cache.put(event.request, copy)) return response }) .catch(() caches.match(event.request)) ) return } })提示别把 API 请求的缓存版本号和静态资源混在一个 Cache Storage 里。分开管理后期排查问题会轻松很多。我在版本号里带了构建时间每次发布新版本只需要修改一个常量旧缓存自动清理。2.3 商品列表与详情缓存的时间窗口设计接口数据虽然走 network-first但不能无限期缓存。电商商品有价格波动、库存变化缓存时间过长会引发用户投诉。我在cache-config.js里定义了一套时间窗口规则缓存对象缓存策略有效时间说明首页推荐商品network-first5 分钟促销位变化频繁商品列表页network-first10 分钟排序、筛选条件影响数据商品详情页network-first30 分钟核心数据价格库存字段以服务器为准商品图片cache-first永久图片不常变更购物车接口network-first不永久存只做弱网兜底不允许过期读取这个表格不是拍脑袋定的是结合业务复盘的结果。名单页商品如果 30 分钟不更新用户会看到“已抢光”但实际还有货这个体验不能忍。而详情页 30 分钟窗口是个折中值既能离线兜底又能保证用户在下单时看到的是较新的库存。实现的时候别把时间逻辑放在前端业务代码里最好是 Service Worker 在缓存 Response 的时候记录时间戳读取的时候比对。写法上可以用cache.put时往 header 里塞一个自定义标记也可以用单独的 Map 记录 URL 与过期时间的对应关系。我个人更推荐后者代码可读性高而且不会污染 Response 对象。2.4 缓存降级与失效后的兜底逻辑缓存策略再完善也一定要设计降级路径。我碰到过一个真实案例Service Worker 缓存的商品详情页不巧是一个已经下架的商品用户点开看到旧信息然后点击购买后端返回“商品已下架”。这时候用户体验已经受损了。所以 data 接口的缓存响应里接口字段需要带一个timestamp前端读取缓存数据的时候比对是否过期过期就弹出加载态并强制走网络而不是把缓存数据直接渲染。代码大致是这个思路// api/product.js async function getProductDetail(id) { const cacheData uni.getStorageSync(product_${id}) if (cacheData Date.now() - cacheData.timestamp 30 * 60 * 1000) { // 还有效先用缓存渲染 renderProduct(cacheData.data) // 同时后台静默刷新 refreshProduct(id) } else { // 无效或不存在直接请求网络并显示加载态 const freshData await request(/api/product/${id}) uni.setStorageSync(product_${id}, { timestamp: Date.now(), data: freshData }) renderProduct(freshData) } }这个逻辑虽然听起来简单但它回答了一个核心问题PWA 的缓存到底是为了“快”还是为了“有”。我的答案是在电商场景里缓存首先是保证“有”——哪怕数据旧一点用户至少能看到页面结构而不是白屏在这个前提下再去追求“快”。细节上注意别把敏感字段价格、库存的最终判断完全托付给缓存最终下单时后端兜底校验是必须的。3. 购物车持久化本地优先全端同步3.1 购物车数据结构设计本地状态和服务端状态的桥接购物车是电商里最需要持久化的数据也是我见过翻车最多的模块。常见错误是购物车数据只放在内存变量里用户一切页面就没了或者过度依赖服务端每次加购都等接口返回弱网环境下点加购没反应用户会疯狂重复点击最后生成一堆重复条目。我用的方案是“本地优先服务端同步”本地是唯一事实来源服务端是云端备份。也就是说用户加购、改数量、删除都是先改本地存储页面立即响应然后异步把变更推给服务端。这样即使用户断网购物车也能正常使用联网后再合并数据。购物车的数据结构我设计成扁平化方便持久化和 diff 合并{ version: 1, items: [ { skuId: 128733, productId: 8891, title: 轻量防晒衣, price: 199, image: http://cdn.example.com/img/8891.jpg, quantity: 2, selected: true, updateAt: 1697429384000 } ], updatedAt: 1697429400000 }每个 SKU 的updateAt字段非常重要后面多端合并的时候就靠它判断谁新谁旧。selected字段是电商购物车的“全选/单选”状态也要持久化否则用户每次打开购物车勾选状态都重置依然后面结算时一脸懵。3.2 持久化选型uni.setStorageSync 与 IndexedDB 怎么配合Uniapp 提供了uni.setStorageSync和uni.getStorageSync底层在 H5 端是 localStorage在小程序端是 wx.setStorage。购物车这种中等量级的数据几十个条目直接用uni.setStorageSync就足够了代码最简单不需要异步回调读写都方便。但有一个边界情况必须注意如果购物车条目多到上百或者你想存储商品列表缓存几百条商品数据localStorage 的容量瓶颈一般 5MB 左右就会冒出来。这时候我建议引入 IndexedDB 存大数据localStorage 只存轻量数据。不过 Uniapp 的 H5 端没有统一的 IndexedDB API我直接用原生window.indexedDB封装一层即可。实际项目里我做了个简单的二八法则购物车、用户信息、最近浏览记录这些轻量的用 storage商品列表缓存、订单历史列表、离线商品图片队列这些重型的走 IndexedDB。混合使用的关键点是封装好读写层屏蔽实现差异。比如做一个storageHelper购物车模块只调addToCart()、getCart()内部决定用哪套存储。3.3 匿名购物车与登录购物车的合并策略用户没登录的时候加了购物车登录之后怎么办这是电商 PWA 里必须处理的场景。无脑覆盖会把游客模式下加购的商品清空不做合并又会出现登录前后购物车“变来变去”的问题。我的实现思路是把购物车合并拆成三步读取本地游客购物车key:cart_guest如果存在就暂存起来。登录成功后拉取服务端购物车得到用户历史云端购物车。按 SKU 维度做合并同一个 SKU数量取两者之和但上限设成 99防止脚本刷量不同 SKU直接合并已下架的 SKU 标记为失效不参与结算。合并完成后本地购物车直接替换成合并结果服务端也同步一份最后清掉cart_guest。关键细节是合并的版本冲突判断如果本地某个条目的updatedAt比服务端新用户刚离线加购过以本地为准反之以服务端为准。这就是我设计updateAt字段的用处。这个合并策略在“登录后回到购物车页面”这个动作发生的时候执行属于页面级事件不会消耗太多性能。3.4 多端同步的冲突处理与页面级联动电商项目通常是多端并存的用户可能在小程序里加购然后在 H5 PWA 里打开想看购物车。两边的购物车数据一定要靠服务端同步否则各存各的用户就会骂街。我的做法是每次进入购物车页面先渲染本地最新数据然后异步拉取服务端购物车整合后端返回的 diff变更的部分更新本地。这个整合过程需要处理两类冲突同 SKU 数量不同步时以后端订单可下单数量为准并把差异通过 toast 提示用户商品价格变动时以服务端价格为准本地缓存的价格仅用于页面快速渲染结算价一律走服务端。这里需要注意一个坑PWA 的页面可能是缓存的购物车页面如果被 Service Worker 缓存了用户打开的时候加载的可能是上次的 JS 代码本地全新的购物车数据可能无法及时反映。所以购物车这种强动态页面必须走“网络优先、缓存兜底”的策略甚至可以在 SW 里对购物车相关路由跳过缓存。4. 支付流程优化从下单到收单全链路4.1 PWA 环境下的支付特殊性比想象中复杂PWA 做支付最尴尬的问题是它同时存在于浏览器、微信内置浏览器、以及“被添加到桌面的独立窗口”三种环境里。同样是用户点击“立即支付”在微信内置浏览器里可以调起微信 JSSDK 支付在普通浏览器比如 Safari、Chrome里微信支付走的是 NATIVE 支付扫码或跳转 App在 PWA 独立窗口里页面没有地址栏跳转支付网关再跳回来的体验会有点奇特但技术上是可行的。很多团队在 PWA 里做支付失败原因不是支付接口不会调而是没有提前区分当前所处的环境。我在项目中封装了一个getPayEnv()方法用来判断当前环境// utils/payEnv.js export function getPayEnv() { const ua navigator.userAgent.toLowerCase() const isWechat /micromessenger/.test(ua) const isAndroid /android/.test(ua) const isIOS /iphone|ipad|ipod/.test(ua) const isStandalone window.matchMedia((display-mode: standalone)).matches return { isWechat, isAndroid, isIOS, isStandalone } }拿到环境之后支付方式的优先级就清晰了微信内置浏览器里走公众号支付JSSDK 拉起微信收银台普通手机浏览器里走 H5 支付调起浏览器内置的微信/支付宝收银台PWA 独立窗口环境视支持情况降级到扫码支付或 App 跳转。这一层判断不做支付流程就很容易跑不通。4.2 三段式支付预下单、拉起支付、回跳确认电商支付流程不能只有一个“调起支付”按钮就完事我把它拆成三段第一段预下单。用户点击“去支付”前端先向后端发起预下单请求带着订单号、金额、商品信息、用户标识。后端校验订单状态是否已支付、金额是否一致生成支付参数返回给前端。这个环节有个关键点前端不能直接用购物车金额作为支付金额必须以服务端重新计算的价格为准否则用户改本地缓存的价格再下单就会变成一笔金额错误的订单。第二段拉起支付。拿到后端返回的支付参数之后根据getPayEnv()的结果选择调起方式。微信内置浏览器用WeixinJSBridge.invoke(getBrandWCPayRequest)普通浏览器用window.location.href跳转到微信支付 H5 网关支付宝用alipay-sdk生成跳转 URL。这时的 UI 反馈至关重要拉起支付之后要立刻进入“订单处理中”的中间态页面防止用户手滑又点了支付导致重复下单。第三段回跳确认。支付完成之后支付平台会回调后端同时浏览器会回跳到一个returnUrl页面。但这里有个经验之谈绝对不能把“支付成功”的最终状态挂在 returnUrl 的 URL 参数上因为用户可能没等回调就手动关掉了支付页面或者 returnUrl 被浏览器拦截。我实际项目中回跳页只做一件事——带着 orderId 进入“订单详情页”页面onShow时向后端查询最新订单状态加上“已知支付成功”的展示态如果查询结果是未支付就提示用户“检测到支付结果未确认点此刷新”。4.3 掉单、重复支付与支付页面缓存的三大坑支付流程里最容易出事故的其实是下面几个边界场景。掉单处理。用户支付成功但后端没收到回调。这个情况在真实环境里出现概率不低原因是回调延迟、网络丢包、服务端处理异常。作法是在订单详情页加一个“查询订单状态”的按钮用户手动刷新后端状态同时请求头里加一个流水号确保同一订单的查询状态幂等不会因为用户重复点击而产生错误结果。重复支付。用户支付成功后页面的白屏用户以为没成功又付了一次。这个问题的根源是钱扣了但页面反馈不及时解决方式就是上面说的“回跳确认 订单状态轮询”。另外后端必须做好幂等校验同一个订单号如果收到第二次支付请求直接返回“订单已支付”绝不创建第二笔流水。支付页面缓存污染。常见做法是用户打开了支付页这时候 Service Worker 可能已经把支付页面的 HTML 缓存了。如果用户继续支付页面加载的是旧版本支付参数可能不正常。有些支付平台会在跳转 URL 上带 token 参数Service Worker 可能把带旧 token 的页面缓存下来。我在 SW 里对支付相关路径/order/*、/pay/*一律不缓存直接 fetch 网络并且设置Cache-Control: no-cache。这一点很多人会忽略属于踩坑之后的独家经验。4.4 支付过程中的用户体验优化细节支付成功后的反馈时间决定着用户的“安全感”。我实测了很多次从支付成功到页面确认中间如果超过 3 秒没有视觉反馈用户就会焦虑。优化手段有两个。第一个是乐观渲染。当支付平台回调或前端能拿到支付成功的信号时哪怕后端还没有完全确认订单页面先把“支付成功”的 UI 渲染出来同时展示“订单确认中”的状态后台再异步查单。这样用户的心理体验是“成功即反馈”而不会看到正在转圈的加载态。第二个是失败重试引导。如果支付失败别直接丢一个“支付失败”的文案而是要给出具体原因——余额不足、银行卡限额、网络中断、超时未支付等并配上“重试支付”和“更换支付方式”两个明确按钮。电商支付里给了用户明确的下一步行动流失率会降低很多。5. 常见问题与排查实录5.1 Service Worker 不更新改了代码用户还是旧版这是 PWA 电商项目里最经典的坑。开发者辛辛苦苦发了一版新代码结果用户手机上加载的还是上上周的缓存页面。原因在于浏览器的 SW 更新机制是“安装新 SW 之后不会立刻接管页面必须等页面重新加载一次”。有很多用户不关闭浏览器标签页于是旧版本就一直撑着。我采用的方案是给cache-config.js里的CACHE_VERSION加上构建版本号然后结合skipWaiting和clientsClaim让新 SW 立刻激活激活后主动刷新页面// pwa/sw.js self.addEventListener(message, event { if (event.data SKIP_WAITING) { self.skipWaiting() } }) // 主应用里监听 SW 更新 if (serviceWorker in navigator) { navigator.serviceWorker.register(/sw.js).then(reg { reg.addEventListener(updatefound, () { const newWorker reg.installing newWorker.addEventListener(statechange, () { if (newWorker.state installed navigator.serviceWorker.controller) { // 新版本已安装提示用户或直接刷新 if (confirm(发现新版本是否刷新)) { newWorker.postMessage({ type: SKIP_WAITING }) } } }) }) }) }提示自动刷新要克制尤其电商场景用户可能正在填写购物车信息直接强制刷新会造成灾难。我建议弹一个轻盈的提示条“已更新到最新版本”让用户自己选择什么时候刷新。5.2 小米手机与 iOS Safari 的 PWA 细节差异“添加到主屏幕”这个动作在不同系统上表现不一致。iPhone 的 Safari 里需要点分享按钮然后选“添加到主屏幕”小米手机上浏览器菜单里通常有“添加到桌面”但如果是 MIUI 的浏览器有时需要去浏览器设置里打开“桌面快捷方式”权限才能添加成功。这就是网络热词里“小米手机 pwa 设置”的来源——不少用户反馈在小米手机上添加 PWA 图标后点开却是浏览器而不是全屏 App。技术层面的原因在于 PWA 的 manifest 配置里必须设置正确的display: standalone同时在 iOS 上需要额外的apple-touch-icon和apple-mobile-web-app-capablemeta 标签。我的配置是这样的meta nameapple-mobile-web-app-capable contentyes meta nameapple-mobile-web-app-status-bar-style contentblack-translucent link relapple-touch-icon href/static/img/icon-192.png5.3 iOS Safari 下 Canvas 导出白图问题这个坑不是每个电商项目都会踩但只要做分享海报功能就会遇到。在 iOS Safari 里用 Uniapp 的uni.canvasToTempFilePath导出图片时经常出现导出的图片是白图。排查的路径是逐层定位先确认 canvas 的尺寸合理、draw 回调正确、字体加载完成。但最关键的还是离屏 canvas 跨域图片未设置 crossOrigin导致画布被污染导出全部变白。处理方式是在绘制之前给所有图片对象加上crossOrigin anonymous属性并且把图片缓存在本地再画不要在 draw 回调里立即导出等一个requestAnimationFrame再执行转换成功率会大幅提高。这个场景我写了详细的排查笔记这里不展开等专门开一篇来写但值得先提醒。5.4 电商 PWA 避坑清单速查问题现象解决方案缓存版本升级用户打开旧版页面构建时注入 CACHE_VERSIONSW 版本变更后 skipWaiting 提示刷新购物车丢失清除浏览器缓存后购物车空核心购物车数据同步上云本地 storage 只做加速API 数据过期商品已下架但页面仍可购买下单前强制请求服务端校验支付回调未到账用户已扣款但订单显示未支付订单详情页查询接口幂等设计 手动刷新SW 缓存支付页支付跳转 token 被缓存对/pay/*路径跳过 SW 缓存iOS 白图canvas 导出海报空白设置 crossOrigin延迟导出华为鸿蒙浏览器 PWA 支持添加到桌面失败兼容处理降级为浏览器书签入口6. 写在最后这套方案真正的落地心得把 Uniapp PWA 的电商三件套做完上线我自己最大的感受是这个方案的本质不是“让网页更好看”而是“让网页更可靠”。商品缓存、购物车持久化、支付流程优化听起来是三个孤立的功能点但它们都指向同一个目标——让用户在任何网络状态下都有持续可用的购物体验。如果你正在做一个“先上 H5再补 App/小程序”电商项目我给的建议是不要等 App 开发完了再去优化网页版而是在 H5 阶段就把 PWA 加上。前期多花的精力会在用户留存和兼容性测试上赚回来。而且这套能力是渐进式的先只做购物车持久化再补静态资源缓存最后上支付优化每一步上线都有可感知的收益。最后分享一个项目上线后的小技巧记得在服务端日志里加一个display-mode字段用来区分用户是普通浏览器访问还是 PWA 独立窗口访问。你会发现PWA 用户的平均停留时长和加购转化率大概率比普通 H5 访问高出不少。有了这个数据支撑你向业务方证明 PWA 的价值就更有底气了。