PWA 必须包含 start_url、display、icons（192x192 和 512x512 PNG）、name、short_name 字段，且 service worker 需在 HTTPS 下注册并处理 fetch 事件。

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）依然起作用，但两者逻辑不同、优先级也不同。

anything-to-html

将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。

下载

• 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 始终处于“半激活”状态。