企业H5升级PWA实战：Service Worker与缓存策略优化指南

1. 为什么这个时间点值得把企业H5站点升级成PWA

先讲一个我最近在忙的事。公司有个面向企业客户的营销活动站，运营那边拉了一个需求清单，排到前三的分别是：页面在弱网环境打不开、活动投放出去后用户第二次访问还要重新加载半天、以及微信/浏览器里加到桌面这个入口到底怎么引导。这三条需求单拎出来都指向同一个东西——现有的H5站点在“访问体验”和“用户留存”上已经到头了，不是前端代码写得不好，而是H5这套架构本身缺了离线能力和原生级的加载体验。

我接手之后把方案翻了翻，PWA是最适合当前站点形态的升级路径，没有之一。它不是要把站点重写成小程序或者App，而是在现有H5的技术栈基础上，通过Service Worker、缓存策略、manifest配置这几个东西，把原来纯浏览式的页面变成一个“能装到桌面、能离线打开、能秒开二次访问”的Web应用。整个过程代码层面不伤筋动骨，但体验层面的变化是用户能直接感知的。

1.1 H5的硬伤：每次打开都在重新“认识你”

先说清楚我们面临的问题。一个典型的企业H5活动站，用户从朋友圈、企业微信或者短信链接点进来，浏览器要挨个走一遍DNS解析、TCP握手、TLS协商、HTML下载、JavaScript执行、接口请求、图片渲染。这个链路在4G稳定网络下还能接受，一旦到了地下车库、电梯间、商场这种信号不稳定的地方，页面首屏能给你卡十几秒甚至直接白屏。

更磨人的是二次访问的体验。用户上一次已经看过活动规则、填过报名信息，结果第二天再点进来，一切照旧要重新加载，Token过期了就重新登录，静态资源连个304协商缓存都不愿意等。本质上，H5站点是无状态的，服务器不记得你，浏览器也懒得帮你留东西，每次访问都是一场从头开始的“相识”。

而PWA解决的就是这两件事：让页面资源在本地有副本，网络断开也能开；让站点的壳（页面框架、公共脚本、样式、图标字体）不反复下载，只有数据部分走网络。它不是传说中高不可攀的行业标准，就是一套浏览器原生支持的缓存与安装机制。

1.2 PWA到底给企业站点带来了什么

PWA能在首次加载完成后，把站点当成一个容器化的应用存在浏览器里。它主要由三个技术能力撑起来：

• Service Worker：一种独立于页面运行在浏览器后台的JavaScript线程，可以拦截页面发出的网络请求，决定走缓存、走网络还是先缓存后网络。
• Web App Manifest：一个JSON文件，描述应用名称、图标、主题色、启动页，让浏览器可以把站点“安装”到桌面并全屏启动。
• HTTPS：Service Worker只能在安全上下文里运行，这是浏览器级别的安全限制。

落到企业站点的实际收益，我最看重的有三个。第一个是二次打开的速度，基本能做到秒开或者接近秒开，因为HTML、JS、CSS、图片全部命中本地缓存，不占网络带宽。第二个是离线状态下的可用性，用户哪怕在没信号的高铁上，只要之前打开过站点，重新点开还是能看到上次缓存的页面内容，报名状态这些动态数据会提示网络异常但仍保留页面骨架。第三个是桌面的入口，安卓端通过Chrome引导可以“添加到主屏幕”，桌面会生成一个带图标的入口，从形态上已经和原生App差不了太多。

1.3 适合和不适合升级的H5站点特征

别急着套方案，先判断站点适不适合。我这次接手的是一个综合性的活动营销与报名站点，页面结构稳定但有部分强动态内容（报名状态、库存数量、活动倒计时），这种站点属于非常典型的PWA适合对象：结构性资源可以缓存，业务性接口按需更新。我建议拿这张表去对照自己的站点：

站点日常确实存在活动报名高峰期，入口接入企业微信和公众号菜单，投入成本去升级缓存是值得的。如果你的站点是纯内容展示、没有用户回访路径，那PWA的投入产出比就很低，可以暂时不做。

2. 拿自家站点做体检：升级前的评估清单与量化目标

定方案之前不要盲目上代码，我踩过一次不体检直接上Service Worker结果老用户浏览器缓存逻辑混乱的坑。这次我先花了两天时间把站点从三个维度做了体检，把家底摸清楚再动刀。

2.1 审计基础指标：HTTPS、响应式、页面体积

动手之前先回答几个基础问题：

• 站点是否全站HTTPS？Service Worker的注册要求页面本身是HTTPS，这是硬条件。本地开发时localhost是例外，但生产环境必须是HTTPS。如果站点还在用HTTP协议，第一步不是PWA而是先迁HTTPS。
• 页面是否响应式？PWA的桌面安装模式里，如果页面在宽屏下布局和用户预期差异太大，宁可暂时不做桌面适配，只针对移动端体验做优化。
• 页面体积和首屏阻塞资源是多少？我在Chrome DevTools的Network面板里看，当前首页HTML约156KB（含内联脚本和样式）、首屏JavaScript打包产物gzip后约128KB、首屏图片资源合计约600KB，三方统计脚本和服务端异步注入占了额外一部分。这些数据直接决定了缓存策略里的“预缓存清单”和“首次加载白屏时长”。

2.2 选哪种缓存策略：Network First还是Cache First

缓存策略是整个PWA方案的核心决策点。行业里有几套经典策略，我这里先用一句话给大家做区分：

• Cache First（缓存优先）：命中缓存就不发网络请求，速度最快，但内容一旦变了要等缓存版本更新才能感知，适合资源指纹不变的静态文件（如main.a8e2c.js）。
• Network First（网络优先）：先请求网络，网络失败或超时再回退到缓存，成功率最高，但代价是每次都要等待网络请求的往返，弱网下可能回退不及时，适合首页HTML这类信息时效性较强的入口页。
• Stale-While-Revalidate（后台更新）：先用缓存内容响应用户，同时在后台发起网络请求更新缓存，下次访问就是新数据，适合Icons这类需要快速展示且可以容忍延迟更新的资源。
• Network Only：只走网络，不做缓存，适合需要实时校验的接口和支付类敏感请求。

对于企业H5站点，我最终采用的是分层组合，而不是全站统一套一种策略。HTML入口页使用Network First，静态资源和图片使用Cache First，页面内个别接口做Network-Only或短时缓存，具体实现在后面的章节里展开。

2.3 量化目标：没有指标的PWA升级等于原地打转

升级技术选型可以很感性，但效果必须有数据支撑。这次项目我在动工前定下了几个可量化的目标值，上线后拿监控数据对照，一个都不许打折扣：

• 首屏二次加载时间（从输入URL到可交互）目标压到1秒以内，用Lighthouse模拟4G网络做前后对照。
• 弱网离线场景（DevTools Network里切到Offline）下，首页能完整显示上次缓存的页面骨架，而不是白屏或系统错误页。
• Service Worker覆盖率：正常在线访问五次后，Lighthouse的PWA面板里“Fast and reliable”相关项达到绿色及格线以上。

我跟团队同步这些目标时特意强调一句：如果升级方案做完之后不能让用户感觉到“变快了”，那只是在给老板汇报PPT时多一个词而已。PWA的技术实现不难，难的是你有没有停下来把目标量化清楚。

3. Service Worker接入第一课：注册、预缓存与生命周期坑

Service Worker是整个PWA的“大脑”，也是最容易让H5开发者产生困惑的部分。它能在网络请求到达服务器之前优先拦截，并从缓存返回之前保存的资源，这意味着我们需要关注的重点变成：何时需要缓存，何时需要网络，以及版本切换时如何清理旧数据。

3.1 核心执行流程：注册到激活的三步走

从代码层面看，Service Worker的运行经历注册、安装、激活三个步骤。注册是在页面主线程里通过navigator.serviceWorker.register()加载SW脚本。安装阶段在SW内部触发install事件，这是预缓存静态资源的最佳时机。激活阶段触发activate事件，此时可以清理上个版本的旧缓存。我之前见过不少第一次做PWA的同事直接在install阶段里去缓存请求接口的响应数据，结果SW版本一升级，旧缓存永远得不到清理，接口数据逾期不更新，页面看起来像是被“卡住”了。

第一版代码我建议写得克制一点，只做预缓存和版本清理这两件事，不要一口气把所有运行时资源都塞进去。最小可用版本大概是这个结构：

javascript复制const CACHE_NAME = 'campaign-shell-v1';
const PRECACHE_URLS = [
  '/',
  '/index.html',
  '/assets/main.6b0d.js',
  '/assets/common.98fd.js',
  '/assets/activity.css',
  '/assets/logo.svg',
];

self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => cache.addAll(PRECACHE_URLS))
  );
  self.skipWaiting();
});

self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((keys) =>
      Promise.all(
        keys.filter((key) => key !== CACHE_NAME).map((key) => caches.delete(key))
      )
    )
  );
  self.clients.claim();
});

不要小看这段代码，里面隐藏着三个初学者最容易踩的坑。

3.2 坑一：注册路径决定了你的缓存“管辖范围”

Service Worker的作用域默认是它所在目录的路径。如果SW文件放在/static/sw.js，它只能控制/static/路径下的页面请求。要控制全站，最常见的做法是把SW文件放在站点根目录/sw.js，或者在注册时显式指定{ scope: '/' }，同时服务器要返回允许该作用域的响应头（必要时候配Service-Worker-Allowed）。

我这次把sw.js放在根目录下，虽然会增加一点点构建产物管理成本，但换来的是全站请求可控，活动详情页、报名表单页、静态资源统一走同一个缓存策略，省了很多排查时间。

3.3 坑二：缓存名带版本号，否则一辈子清不掉旧缓存

在activate阶段对上文代码keys.filter(key !== CACHE_NAME)要做严格判断。我发现不少人有个懒习惯，直接caches.delete(keys[0])，一旦有多个缓存名称，删除顺序错误就会删除到正在使用的新缓存。

一个稳定且简单的规则是：每次发版时修改CACHE_NAME版本字段，比如从v1改到v2，activate阶段逐一对比并删除不属于当前版本的所有缓存。这样在用户第二次打开页面时，“旧SW控制页面 → 新SW后台安装并激活 → 旧缓存被清空”这个流程会自动完成，不用等用户手动清浏览器缓存。

3.4 坑三：预缓存列表不能拍脑袋，要和构建产物清单挂钩

如果你手写预缓存列表，每次前端打包改了文件名，都很容易漏。我在这次项目里接入了workbox-build的命令行工具，自动把打包产物里的文件名列表同步到SW的预缓存清单中，核心配置大概是：

bash复制npx workbox generateSW workbox-config.js

其中workbox-config.js里关键配置是这样：

javascript复制module.exports = {
  globDirectory: 'dist/',
  globPatterns: ['**/*.{js,css,html,svg,png,webp}'],
  swDest: 'dist/sw.js',
  skipWaiting: true,
  clientsClaim: true,
  runtimeCaching: [
    {
      urlPattern: /\.(?:png|jpg|jpeg|svg|webp)$/,
      handler: 'CacheFirst',
      options: {
        cacheName: 'campaign-images',
        expiration: { maxEntries: 60, maxAgeSeconds: 30 * 24 * 60 * 60 },
      },
    },
  ],
};

这份配置让dist输出目录下的静态资源全部纳入预缓存，同时对图片类请求做了运行时缓存兜底，避免用户首次访问时因为某个图片还没载入而白白发起网络请求。在真实项目里，我不会推荐手写一堆运行时缓存逻辑，直接用Workbox的路由配置，省事且稳定。

4. 缓存策略实测：页面壳、静态资源、接口的最终选择

很多讲PWA的文章会把缓存策略列成一个表格然后结束，但在真实项目里怎么分场景应用，才是最啰嗦也是最有讲究的一环。我基于这个活动报名站点的实际流量特点和页面结构，把线上请求按类型拆成四类，分别定了不同的缓存策略，实测跑了一周数据，整理如下。

4.1 页面壳（Navigation Request）：Network First + 超时兜底

页面壳指用户首次访问的HTML入口文档。这个文件包含了页面骨架、meta信息、首屏脚本地址，如果把它做成Cache First，一旦服务端更新了页面结构（比如运营改了活动规则），用户下次打开拿到的还是本地旧HTML，新版本永远无法触达。所以这里我采用Network First + 超时兜底模式，实现方式在Workbox里可以配置为：

javascript复制registerRoute(
  ({ request }) => request.mode === 'navigate',
  new NetworkFirst({
    cacheName: 'campaign-pages',
    networkTimeoutSeconds: 3,
    plugins: [
      new ExpirationPlugin({
        maxEntries: 20,
        maxAgeSeconds: 7 * 24 * 60 * 60,
      }),
    ],
  })
);

这个策略的意图很明确：在线状态下，用户始终拿最新的页面壳。网络请求超过3秒还没返回时，回退到缓存副本，避免白屏。离线和弱网时这个回退机制会被激活，用户看到的是上一次打开时的页面现状，至少不是“无法连接”的浏览器错误页。实测在4G弱网下，缓存命中后的页面显示时间比直接请求服务器足足快了近一半，用户体感提升非常明显。

4.2 静态资源与图片：Cache First + 按数量和时效限制缓存水位

对带hash指纹的js/css，文件名一变内容就变，文件名不变内容一定没变，用Cache First是绝对安全的。图片处理复杂一点，运营会不定期替换配图，但图片URL经常不变。我做了两层控制：按数量限制最大缓存条目数，避免容量无限膨胀；按时间限制最长缓存时长，我定为30天，超过后即使URL不变也会重新发一次网络请求回源校验。

javascript复制registerRoute(
  ({ request }) => request.destination === 'image',
  new CacheFirst({
    cacheName: 'campaign-images',
    plugins: [
      new ExpirationPlugin({
        maxEntries: 60,
        maxAgeSeconds: 30 * 24 * 60 * 60,
      }),
    ],
  })
);

有一个经验值得强调：如果把图片的maxEntries设置太大，老图片的缓存会把空间全部占掉，导致新图片存不进去或者触发浏览器整体缓存淘汰策略，到时候行为会变得不可预期。我过去吃过这个亏，某次活动上线后大量新图无法进入缓存，页面反而比没有PWA时更慢。

4.3 业务接口：谨慎中的谨慎，我只缓存三类

讨论接口缓存时，项目组里吵过一轮，有人主张全站接口都可以Network Only，安全第一。我的判断是，如果接口完全不做缓存，PWA的离线体验就废了一半；如果缓存所有接口，报名状态、Token刷新这类强实时数据被缓存，后果很严重。最终我只挑三类接口做有限时长的缓存：

• 活动基础信息接口（活动名称、时间、规则富文本，内容更新频率按天计算），设置6小时的缓存时间。
• 公告/消息列表接口，可以容忍5分钟内的新数据延迟。
• 首屏静态化配置接口（比如页面主题色、是否开放报名），设置30秒短缓存，挡住瞬时高并发。

实现方式是Network First + 短时缓存，配合networkTimeoutSeconds: 0.5，0.5秒内网络不返回就直接用缓存先把页面铺出来，后台再偷偷更新数据。报名提交、验证码、Token校验这类接口保持纯网络请求，不做任何缓存。

javascript复制registerRoute(
  ({ url }) => url.pathname.startsWith('/api/activity-info'),
  new NetworkFirst({
    cacheName: 'campaign-api-activity',
    networkTimeoutSeconds: 0.5,
    plugins: [
      new CacheableResponsePlugin({
        statuses: [0, 200],
      }),
      new ExpirationPlugin({ maxAgeSeconds: 6 * 60 * 60 }),
    ],
  })
);

4.4 缓存容量和线上数据复盘

在Chrome的Application面板里，我观察了第一周线上运行后的缓存情况：页面壳缓存量约80KB，apis活动信息约3组响应，图片缓存峰值约38张，总体积没有超过5MB。这个容量对大多数企业站点来说是可接受的，没有触达浏览器对某站点的配额限制。

复盘数据里有两条值得写出来：第一，弱网用户平均页面加载时间从之前的8.4秒降到了3.1秒左右，其中绝大多数对HTML的请求都回退到了缓存；第二，用户“重新打开页面就走新的静态资源更新流程”这个预期达成了，理论上每次老用户刷新页面时，浏览器都会在后台静默拉取最新资源，老缓存自动淘汰，没有产生一次“用户已经是最新页面却看不到新活动”的投诉。

5. 常见问题排查与工具链：从Lighthouse到真实设备验证

代码写完不等于上线成功，PWA方案还需要经过一套完整的验证流程。如果直接在代码主干上push上去，风险会比较高，特别是Service Worker的更新机制与普通JavaScript不太一样，一旦旧SW活着，新代码很难在同一次会话里生效。我习惯把这套验证拆成四步。

5.1 Lighthouse审计的重点指标解读

在Chrome DevTools的Lighthouse面板里选择“Application”类别跑一遍，其中会输出PWA相关的几个核心审计项，我这里简单说下怎么读：

• 是否为HTTPS：如果是红，先处理证书，否则SW注册直接失败。
• 页面在离线时是否可用：需要手动切到Network Offline再刷新页面验证。
• 安装了Web App Manifest且start_url加载正常：注意start_url最好是相对路径，不能是/index.html?utm_source=xxx这种带查询参数的地址，否则在部分浏览器里会跳回带参URL。
• 首屏加载速度指标：Lighthouse的Performance分数会明显受缓存策略影响，但不能只看分数，要看“第二次空载访问”时的Speed Index提升。

跑Lighthouse有个容易忽视的点：DevTools里如果“Disable cache”勾选过，Lighthouse测出来的效果会不准确，因为它把离线缓存那个部分当成无效访问来处理了。

5.2 开发中最容易踩的四个运行期问题

我用了一个下午专门做回归测试，并对照排查文档，发现四个高频问题值得提醒大家：

• Service Worker更新了，但页面打死不生效：用户打开页面后可能停留在老Tab很久，老SW仍然控制页面。解决方法是保证skipWaiting()和clientsClaim()在SW里注册，同时建议在前端加一个“检测到新版本，刷新页面”的提示。检测代码可以通过监听registration.onupdatefound实现，发现新SW后弹一个消息提示用户手动刷新。
• 缓存了不该缓存的请求：我见过有人直接caches.addAll(['/api/xxx'])，导致用户提交的敏感参数被缓存在本地。排查时可以直接在DevTools的Network里查看哪些请求来自ServiceWorker，对不该命中的请求逐一核对路由拦截规则。缓存API响应时用CacheableResponsePlugin限定只缓存状态码200的对象，避免浏览器把304之类的响应也塞进缓存。
• 桌面端首次安装不显示“添加到主屏幕”的入口：在安卓Chrome里，Web App Manifest的图标必须至少包含192px和512px尺寸的PNG，否则Chrome不展示安装提示；苹果Safari不支持安装到主屏幕的按钮，但可以引导用户通过“分享->添加到主屏幕”实现。
• 引用的外部资源跨域导致预缓存失败：比如页面里用了https://cdn.other-domain.com/utils.js，cache.addAll对跨域请求会失败，要么把资源换成同域，要么通过运行时缓存的方式绕过“预缓存失败会拒绝install事件”的限制。我这次直接检查了所有预缓存URL的响应头，确保没有no-store和跨域限制。

5.3 真实设备验证清单

代码部署到测试环境之后，不要只在PC DevTools里测完就收工。建议拿真机走一遍下面的清单，我发现很多问题在DevTools里看不出来：

• 安卓Chrome：安装到桌面，打开应用是否全屏且状态栏颜色正常；离线状态（开启飞行模式）打开一次看是否显示缓存页面；回到在线状态后，二次打开是否自动更新数据。
• iPhone Safari：因为iOS系统对PWA支持限制较多，重点看表单和报名流程是否在离线时还能填写（如果不行，必须有明确的离线提示文案）；检查viewport-fit=cover的布局是否导致刘海屏遮挡底栏。
• 企业微信内置浏览器：部分版本对Service Worker的更新策略有自己的缓存逻辑，如果企业微信内置的X5内核不能正常注册SW，至少不能让页面报错，需要做降级处理——页面正常打开走HTTP，缓存逻辑不生效但不阻塞使用。

5.4 升级到PWA后更容易忽略的一环：版本发布与回滚

PWA的发布比普通H5多一道工序。普通H5改一行文案，重新发一遍页面就完事；PWA发版要保证新的SW被推下去并重新缓存新资源。我的做法是把SW脚本和预缓存清单作为前端构建产物的一部分，每次发版时生成新版本号。回滚时注意一个问题：如果用户浏览器本地已经缓存了带老版本SW的页面，做线上回滚不等于用户端自动回滚。必要时候可以把缓存版本号提升一个版本，并临时发布一份“仅清空缓存，不缓存任何内容”的SW，让老用户回到最原始的纯线上状态。

6. 在过程中沉淀的一些实际体会

这一篇写到这里，我并没有把后端改造、HTTPS证书迁移等外围内容展开，因为那不是PWA本身的重点。如果看完你还想接着动手，我的建议很清晰：拿一个访问量不大但路线清晰的企业站点试水，把Service Worker的壳子先跑起来，再加缓存策略，最后把manifest补上。别一上来就图完事。

我也建议你做完之后多逛一逛真正上线了PWA的站点，在Chrome的DevTools里看它们如何处理请求，点开Application面板看缓存名称和资源列表。我从这些站点里学到的模式，比翻官方文档管用得多。

再说两点让人少走弯路的经验：一是Service Worker版本间的切换逻辑，花时间在“发布与回滚”上比在“策略选择”上更值得，因为一个活跃用户量级过十万的站点，一旦出现旧SW霸占页面，那些老用户会在很长一段时间里看不到新版本。另一点就是缓存容量管理，要给运营活动配图留出余量，不然一次图片量较大的活动就能把缓存水位直接顶爆。

这次升级持续了大概三周，中间有一个下午专门在处理企业微信内置浏览器的兼容差异。但收尾时看到数据面板上的二次访问耗时降到一秒内，报名转化率也有微幅提升，那种“纸面上的技术方案真的在用户端起了作用”的感觉，还是值得的。最后祝你们的PWA升级也顺利，有具体问题欢迎评论区交流，我看到都会回。