HTML转PWA应用步骤｜网站升级PWA指南

想让网站真正升级为功能完整、体验媲美原生应用的渐进式Web应用（PWA），关键不在复杂代码，而在于精准落实几个不可妥协的核心配置：manifest.json中start_url、display、192x512图标、name和short_name五大字段缺一不可，service worker必须在HTTPS下正确注册并主动响应fetch事件，离线策略需按资源类型精细设计（如HTML用Stale-While-Revalidate、JS/CSS用Cache First），而Lighthouse检测失败往往只因三个“小疏忽”——start_url返回非200、图标路径404或sw未调用respondWith()。修复这些硬性门槛，你的网站就能瞬间解锁添加到桌面、离线可用、推送通知等PWA核心能力。

manifest.json 配置必须包含哪些字段才能被识别为 PWA

浏览器只认 manifest.json 里几个关键字段，缺一不可，否则连“添加到桌面”都不会触发。最常漏掉的是 start_url 和 display。

• start_url 必须存在，且需是相对路径或同源绝对路径（如 "/" 或 "/index.html"），不能是外部链接
• display 推荐设为 "standalone" 或 "minimal-ui"；设成 "browser" 就退化成普通标签页，不算真正 PWA
• icons 至少提供一个 192x192 和一个 512x512 的 PNG（WebP 不支持），且 src 路径要能被 fetch 到（404 会导致 manifest 加载失败）
• name 和 short_name 都得有，short_name 用于桌面图标文字，过长会被截断

service worker 注册失败的典型原因和验证方法

注册失败不报错，但控制台会静默跳过——这是最让人困惑的地方。核心问题往往不是代码写错，而是环境或路径没对上。

• 必须在 HTTPS 下运行（localhost 是唯一例外，HTTP/127.0.0.1 不行）
• navigator.serviceWorker.register() 的参数路径是相对于页面 URL 的，不是相对于 JS 文件位置。比如页面在 /blog/post.html，想注册根目录下的 sw.js，得写 navigator.serviceWorker.register("/sw.js")，而不是 "./sw.js"
• 注册后立刻刷新页面看不到效果：service worker 默认要等下次页面加载才激活，可用 skipWaiting() + clients.claim() 强制接管，但仅用于开发调试
• 检查是否生效：打开 DevTools → Application → Service Workers，看状态是不是 “Activated and is running”，同时勾选 “Update on reload”

离线缓存策略怎么选：Cache API vs HTTP 缓存

很多人以为加了 service worker 就自动离线可用，其实默认什么也不缓存。你得自己决定哪些资源进 Cache API，而 HTTP 缓存（如 Cache-Control）依然起作用，但两者逻辑不同、优先级也不同。

• HTML 页面建议用 Stale-While-Revalidate 策略：先返回缓存，再后台更新，避免白屏；直接 cache-first 容易卡在旧版本
• JS/CSS 资源适合 Cache First，但记得在 service worker 更新时清旧缓存（用 cache.keys() 遍历删除）
• API 请求别盲目缓存：带用户态的接口（如 /api/user/profile）缓存前必须校验 auth token 或加用户 ID 到 cache key
• 注意 fetch() 默认不带 cookie，需要显式传 { credentials: "include" }，否则登录态请求会 401

Lighthouse 检测不通过的三个硬伤点

Lighthouse 的 PWA 分数低，通常不是因为功能没做全，而是卡在几个具体可验证的细节上，改完立刻见效。

• start_url 返回非 200（比如重定向到 login 页面）→ 直接判失败。确保该 URL 可以无条件返回 HTML
• manifest 中的 icons 少于两个尺寸，或任意一个返回 404 → Lighthouse 会忽略整个 manifest
• service worker 没处理 fetch 事件，或者监听了但没调用 event.respondWith() → 页面仍走网络，离线即挂

这些点都不难改，但容易被当成“小问题”拖着不修，结果 PWA 始终处于“半激活”状态。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《HTML转PWA应用步骤｜网站升级PWA指南》文章吧，也可关注golang学习网公众号了解相关技术文章。