PWA究竟是什么？如何打造高效率的离线Web应用？

PWA打造离线Web应用的核心，不是给网页加个安装按钮，而是用Service Worker、缓存策略和本地存储把“断网还能用”做成可维护的工程能力。对前端文档工具和图表页面来说，离线可打开、数据可回读、更新可控制，比“看起来像App”更重要。

PWA离线Web应用怎么做：从Service Worker到缓存策略

别急着上Workbox。先把离线边界画清楚：哪些页面必须能打开，哪些数据可以旧一点，哪些请求绝不能缓存。边界清楚，缓存策略才不会变成线上事故来源。

先确认离线边界：哪些页面必须能开

• 文档首页、目录页、最近阅读页，属于必须离线可打开的壳。
• 图表页的JavaScript、字体、图标、主题CSS，属于静态资源，适合预缓存。
• 图表数据集JSON、筛选条件、用户标注，属于动态数据，要分层缓存。
• 登录、支付、权限校验接口，走网络优先，不缓存响应体。

据MDN Web Docs公开文档，Service Worker能拦截网络请求并返回缓存响应。它的能力很强，但前提是页面至少成功访问过一次。首次访问仍需联网，这是PWA离线能力的事实边界。

Service Worker和manifest的落地路径

manifest.webmanifest

在静态资源目录放一份manifest，至少写清name、short_name、start_url、display: standalone、icons。据W3C Web App Manifest规范，standalone显示模式用于提供接近独立应用的窗口体验。图标要准备多尺寸，别只放一张大图让浏览器硬缩。

注册与更新

在入口文件注册Service Worker，路径决定作用域。放在根目录/sw.js，通常能覆盖全站；放在/docs/sw.js，默认只控制/docs/下的页面。

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/sw.js');
  });
}

更新时不要无脑skipWaiting。文档站和图表工具可能有未保存标注，直接接管会让旧页面读到新缓存。缓存版本号必须可追踪，例如docs-v3、chart-v5，并给用户一个“刷新以更新”的提示入口。

Workbox缓存策略

用Workbox可以减少手写缓存逻辑。常见配置思路是：应用壳precache，图片和字体CacheFirst，文档JSON和图表配置StaleWhileRevalidate，权限接口NetworkOnly。运行时缓存加上过期条数，避免缓存无限膨胀。

runtimeCaching: [{
  urlPattern: //api/charts//,
  handler: 'StaleWhileRevalidate',
  options: {
    cacheName: 'chart-data',
    expiration: { maxEntries: 50, maxAgeSeconds: 86400 }
  }
}]

这段配置的可验证点在Chrome DevTools。打开Application > Service Workers看状态，再切到Network勾选Offline刷新页面。能打开壳、能读到上次图表数据，才算离线链路跑通。

图表与文档数据的离线分层

图表库本身不是难点。ECharts、Chart.js的脚本和主题文件走预缓存即可。难的是数据：请求型JSON放Cache Storage，用户标注和较大数据集放IndexedDB，偏好设置放localStorage。别拿localStorage存图表大数据，同步读写会卡主线程。

• 01
  文档站

  HTML、JS、CSS、搜索索引做预缓存，图片走运行时缓存。

• 02
  图表页

  图表配置和数据接口分开缓存，接口缓存名带业务前缀。

• 03
  离线回读

  页面启动先读IndexedDB，再发网络请求校正。

• 04
  恢复同步

  网络恢复后重试失败请求；Safari对后台同步支持有限，可在页面可见时触发重试。

PWA和原生App的区别在哪：文档工具与图表场景的选型对比

业内专家指出，PWA与原生App的差距主要集中在深度系统能力、推送生态和后台任务，常见文档阅读、图表查看、弱网办公并不需要为此全部重做原生。

PWA适合哪些场景：文档站、图表工具与弱网办公

• 01
  内部文档站

  员工在会议室、出差路上断网查看手册和规范。

• 02
  图表看板

  弱网环境先展示上次数据，联网后自动校正。

• 03
  代码笔记工具

  离线编辑草稿，恢复网络再同步。

• 04
  活动页和轻应用

  不想走应用商店，又要安装入口和离线壳。

国内PWA部署注意事项

国内PWA部署注意事项不复杂，但容易漏。站点必须HTTPS；Service Worker作用域要和路由规划一致；CDN缓存头别把sw.js长期缓存；跨域字体和图表数据要配置CORS；iOS对推送和后台同步的支持与Android存在差异，功能设计要做降级。面向国内用户时，还要把备案、CDN节点和首屏资源体积一起算进体验账。

前端文档工具里的PWA实践：图表绘制与代码经验

文档站接入PWA的实际路径

VitePress项目可接@vite-pwa/vitepress，Docusaurus项目可用@docusaurus/plugin-pwa。操作顺序是：装插件、配manifest、设预缓存glob、加离线fallback页、跑构建、在DevTools断网验收。静态站点不要把所有历史版本文档都预缓存，按目录和访问频率分批处理。

图表数据缓存：Cache Storage还是IndexedDB

• Cache Storage适合请求和响应，例如图表JSON接口、图片、字体。
• IndexedDB适合结构化数据，例如用户标注、筛选状态、较大数据集。
• localStorage只放主题、语言、最近路由等小偏好。
• 缓存结构要带版本迁移逻辑，升级时清理旧对象仓库，别让脏数据拖慢图表渲染。

更新、灰度与测试命令

• 本地构建后执行npx serve dist，用localhost验证Service Worker注册。
• 在DevTools的Application > Storage清理缓存，模拟首次访问。
• 勾选Offline后刷新文档页和图表页，检查fallback与数据回读。
• 用Lighthouse的PWA检查项看manifest、HTTPS、离线响应，但别把分数当唯一目标。
• 发版时保留旧缓存一个周期，观察错误日志再清，避免用户刚打开就遇到空白页。

PWA开发成本多少钱：改造量与团队配置的粗略账

PWA开发成本多少钱，没有统一报价。已有响应式文档站接PWA插件，主要花在前端配置、缓存策略和测试上；带协作标注、图表大数据、离线同步的工具，成本会明显上升。按人力天估算比按“一个PWA多少钱”更靠谱。

成本构成

• 01
  前端改造

  入口注册、manifest、Workbox配置、离线fallback。

• 02
  数据层

  IndexedDB建模、版本迁移、冲突处理。

• 03
  测试

  断网、弱网、多机型、缓存更新、权限失效。

• 04
  维护

  缓存版本治理、监控白屏、CDN缓存头检查。

行业共识认为，PWA的长期成本不在“第一次接上”，而在缓存治理和更新策略。团队没有HTTPS、构建流水线和线上监控，先把基础打好再谈离线。

什么情况不建议上PWA

• 业务强依赖蓝牙、USB、深度后台任务或完整推送生态。
• 首屏资源极大，离线包体积失控，用户安装意愿低。
• 数据实时性极高，离线旧数据会直接造成误判。
• 团队没有缓存版本管理和灰度发布能力。

把离线当成产品能力，而不是缓存插件。PWA能解决“断网还能看、弱网还能用”的问题，但解决不了所有系统级能力和数据冲突。

PWA打造离线Web应用常见问答

PWA离线Web应用怎么做才不白屏？

先预缓存应用壳和路由fallback，导航请求用NetworkFirst或StaleWhileRevalidate，静态资源用CacheFirst，权限接口走NetworkOnly。首次访问必须联网，离线能力来自访问后的缓存。验收时在DevTools的Application面板看Service Worker状态，再切Offline刷新页面。

文档工具用PWA缓存图表数据，选Cache Storage还是IndexedDB？

请求型JSON、图片、字体放Cache Storage，配合Workbox管理过期；用户标注、筛选状态、较大数据集放IndexedDB。localStorage只存小偏好，别存图表大数据。缓存名和数据库版本都要带业务前缀，升级时做迁移和清理。

PWA和原生App的区别在离线场景下大吗？

常见文档阅读和图表查看差距不大，深度系统能力、后台同步和推送生态原生更强。PWA的离线能力依赖首次访问后的缓存，首次打开仍需网络。