【推荐收藏】PWA怎么做全套资源大合集

推荐收藏】PWA 怎么做全套资源大合集

一句话总纲：PWA = HTTPS + manifest.json 应用清单 + Service Worker 服务工作线程三大基石;实现桌面安装、离线可用、推送通知、独立窗口运行;本文包含原理、最简代码、缓存策略、工具链、模板、调试、打包上架、踩坑清单，适合原生 HTML、Vue、React、CMS(帝国 CMS / 逐浪 CMS)网站直接改造。

前置硬性门槛：线上必须 HTTPS;localhost本地开发不受 HTTPS 限制，HTTP 域名线上无法注册 Service Worker、无法触发安装弹窗GitHub

一、核心概念与原理

manifest.json(应用清单)：告诉浏览器这是一个 App，定义名称、图标、启动页、主题色、显示模式(standalone 独立窗口)。放在网站根目录，html 通过 link 引入。

Service Worker(sw.js)：后台独立运行 JS，不阻塞页面;生命周期：install安装 → activate激活 → fetch拦截请求;负责离线缓存、资源更新、推送通知、后台同步。

渐进增强：普通浏览器就是网页;Chrome/Edge/ 新版 Safari 支持 PWA，自动解锁桌面安装、离线能力，不兼容浏览器不影响正常访问。

能力清单：桌面 / 手机桌面图标、独立窗口、无浏览器地址栏、离线访问、后台推送、Web Share 分享、Web Payment、后台同步。

二、最简可直接复制代码(原生 HTML 零框架)

1. manifest.json(根目录)

{

"name": "我的PWA应用",

"short_name": "PWA",

"description": "PWA渐进式网页应用",

"start_url": "/",

"display": "standalone",

"background_color": "#ffffff",

"theme_color": "#2563eb",

"orientation": "portrait",

"icons": [

{"src": "/icon-192.png","sizes":"192x192","type":"image/png"},

{"src": "/icon-512.png","sizes":"512x512","type":"image/png"}

]

}

2. index.html 头部引入清单

3. index.html 底部：注册 Service Worker

4. sw.js(基础预缓存模板，根目录)

const CACHE_NAME = 'pwa-cache-v1';

const STATIC = ['/','/index.html','/style.css','/icon-192.png'];

// 安装：预缓存核心静态资源

self.addEventListener('install',e=>{

e.waitUntil(caches.open(CACHE_NAME).then(cache=>cache.addAll(STATIC)))

});

// 激活：清理旧缓存

self.addEventListener('activate',e=>{

e.waitUntil(caches.keys().then(keys=>Promise.all(keys.filter(k=>k!==CACHE_NAME).map(k=>caches.delete(k)))))

});

// 拦截请求：缓存优先(静态资源)

self.addEventListener('fetch',e=>{

e.respondWith(caches.match(e.request).then(res=>res||fetch(e.request)))

})

注意：版本号v1修改后才会触发更新;直接改 sw.js 内容，浏览器会识别变更、触发新版安装。

三、四大缓存策略(必背，不同资源选用)

Cache-First 缓存优先(静态资源：css/js/ 图片 / 字体)：优先读缓存，无缓存再网络，适合不常变化带 hash 资源

Network-First 网络优先(页面、API 动态数据)：优先网络，断网回退缓存页面，适合需要最新内容的页面

Stale-While-Revalidate 先返回缓存，后台更新缓存：头像、资讯列表，兼顾速度和新鲜度

Network Only 仅网络：支付、统计、埋点，禁止缓存

四、全套工具资源【直接收藏】

✅ 在线生成工具(懒人首选)

PWABuilder(核心)：https://www.pwabuilder.com/ 输入网址一键校验 PWA、自动生成 manifest、sw、图标;一键打包安卓、微软商店安装包;VSCode 配套 PWABuilder Studio 插件PWABuilder

PWA Icon Generator：一键批量生成 192/512、苹果 touch、maskable 自适应图标

Manifest 在线编辑器：可视化配置 manifest，实时校验语法

Lighthouse(Chrome 内置)：Audit → PWA，一键打分，列出缺失项、安装、离线、HTTPS 问题

✅ 框架配套插件(Vue/React/Vite 项目)

vite-plugin-pwa(Vite + Vue3/React 首选，基于 Workbox，自动生成 sw，不用手写大量缓存)

next-pwa：Next.js PWA 插件

@angular/pwa：Angular 官方 PWA

Workbox：谷歌官方 SW 库，封装预缓存、路由缓存、后台同步，生产项目优先用 Workbox，不手写原生 sw

Workbox 比手写 sw 更稳定，自动处理版本、更新、路由匹配

✅ 调试工具

Chrome DevTools → Application 面板：

Service Workers：查看状态、更新、跳过等待、模拟离线、bypass 缓存

Cache Storage：查看缓存列表、手动删除缓存

Manifest：清单校验，看图标、start_url 是否报错

Lighthouse：PWA 合规检测

✅ 文档参考

MDN PWA：https://developer.mozilla.org/zh-CN/docs/Web/Progressive_web_apps

web.dev PWA 教程：谷歌官方 PWA 指南

PWABuilder 文档：微软官方打包上架指南

五、模板与脚手架资源

原生 HTML 极简 PWA 模板(GitHub)：仅 manifest+sw + 离线兜底页

create-pwa-boilerplate：Vite+Vue3/React+TS+Tailwind，内置 vite-plugin-pwa、推送 demo、web api 示例

CMS 改造模板(帝国 CMS、逐浪 CMS)：

把 manifest、sw 放在网站根目录

模板 html 头部增加 manifest、theme-color

注意：帝国 CMS 静态页面，sw 缓存策略要适配静态页面更新

离线兜底页模板 offline.html：断网时优雅提示，替代浏览器默认断网页

六、进阶能力：推送通知、版本更新、后台同步

1. 推送 Push 通知(VAPID 密钥)

需要后端，生成 VAPID 公钥私钥;前端订阅，后端推送消息

注意：Safari 推送机制和 Chrome 不同，限制较多;不能页面加载自动弹窗，必须用户点击后申请权限

2. PWA 版本更新(高频踩坑)

原生 SW 默认：新版 install 完成后，等待旧页面全部关闭才接管，用户无感。两种方案：

静默等待(稳妥)：用户关闭页面再打开，自动新版

提示更新(推荐)：skipWaiting + postMessage 通知页面，弹窗提示 “发现新版本，点击刷新”，避免用户一直停留在旧版缓存

3. Background Sync 后台同步

无网络提交表单，联网后自动同步数据，适合表单、留言、离线填报场景。

七、打包上架(PWABuilder 一键打包)

PWABuilder 支持导出：

Android：APK / AAB(可上架 Google Play)

Windows App：微软商店包

iOS：PWA 打包(苹果 App Store 对 PWA 审核较严，优先直接网页 PWA)

重点：iOS Safari PWA 限制多：推送能力弱、缓存有容量上限、桌面图标刷新机制特殊

八、帝国 CMS / 普通静态网站改造 PWA 步骤(适配你之前的帝国 CMS)

网站开启 HTTPS，配置 SSL 证书

根目录上传 manifest.json、sw.js、图标

全局公共头部模板增加 和 theme-color

全局模板底部增加 SW 注册脚本

配置 sw 缓存策略：静态 css/js/ 图片缓存优先，栏目页、内容页网络优先

Lighthouse 检测，修复报错;测试断网、桌面安装弹窗

注意：帝国 CMS 刷新静态，资源变更后，修改 sw 缓存版本号，触发更新

九、高频踩坑清单(90% 人踩坑点)

❌ 线上 HTTP 域名：SW 注册失败，无法安装 ❌ start_url 路径错误、作用域 scope 不匹配：安装后打开 404 ❌ 图标缺少 maskable 图标：安卓桌面图标裁切异常 ❌ SW 缓存版本号不改：修改页面，用户永远读旧缓存 ❌ 缓存 html 页面，页面更新用户看不到：页面类资源不要无脑 cache-first ❌ 苹果 iOS 坑：Safari 不自动弹出安装提示，需要引导用户「添加到主屏幕」;缓存有上限，长时间不用自动清理 ❌ 资源跨域：跨域图片 / 接口无法被 SW 缓存 ❌ 开发调试忘记勾选 Bypass service worker：一直命中旧缓存，看不到修改效果

十、PWA 验收标准(Lighthouse 全部通过)

✅ HTTPS ✅ 有效的 manifest.json，包含 192+512 图标 ✅ Service Worker 注册成功，离线可以打开核心页面 ✅ 可安装(浏览器地址栏出现安装图标) ✅ 响应式，适配手机 ✅ 主题色、背景色配置正常