调试 PWA

一句话： Chrome DevTools 的 Application 面板可以让你检查 PWA 的 manifest、Service Worker 状态与缓存响应，并提供强制更新、切换到离线状态、 以及绕过 Service Worker 直连网络的控制项。

Manifest 面板

根据 Chrome 的文档，DevTools → Application → Manifest 会以“更易读的方式” 展示 manifest 中的 Identity 与 Presentation 字段，列出每个声明的图标（并提供 复选框预览 maskable 图标使用的安全区域），支持测试协议处理程序（protocol handler）注册情况；如果 DevTools 发现问题（例如某个图标加载失败），会显示 Installability 区块并描述该错误。

Service Workers 面板

根据 Chrome 的文档，该面板提供以下控制项：

控制项	作用
Offline	将 DevTools 置于离线模式
Update on reload	强制 Service Worker 在每次页面加载时更新
Bypass for network	绕过 Service Worker，强制浏览器直接请求网络
Update	对指定 Service Worker 执行一次性更新
Unregister	注销指定的 Service Worker
Push / Sync	模拟 push 事件或后台同步事件

该面板的 Status 行会报告 Worker 的状态以及更新次数；根据 Chrome 的 文档，如果 Worker 抛出错误，错误计数会显示在 Source 行旁边。

// 在依赖 Service Worker 之前先进行特性检测。
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
} else {
  // 回退：没有 Service Worker API——应用必须在没有它的情况下也能工作。
}

Cache Storage 与 Clear Storage

DevTools → Application → Cache Storage 是一个只读列表，展示通过 Service Worker Cache API 存储的所有内容；部分条目可能显示为“opaque”响应， 这会影响其大小计入存储配额的方式。根据 Chrome 的文档，DevTools 可能不会 立即检测到缓存变化——如果预期出现的缓存没有出现，请重新加载页面。 Clear Storage 面板可以一键注销 Service Worker 并清除缓存与存储—— 适合在测试运行之间重置到干净状态。

测试离线行为

根据 Chrome 的文档，Service Workers 面板中的 Offline 复选框会将 DevTools 置于离线模式，与 Network 面板中的离线模式等效。根据 MDN 的 PWA 指南，Service Worker 可以拦截网络请求并返回自定义离线页面，而不是 浏览器的通用错误页面——这正是勾选 Offline 时应验证的行为。

适用范围

本指南专门介绍 Chrome DevTools：根据 Chrome 的文档，上文描述的 Manifest、 Service Workers 与 Cache Storage 面板都是 Chrome 自己的开发者工具。本指南 不涉及 Firefox、Safari 或其他浏览器的开发者工具——它们不在本文范围内。

常见问题

• Update 按钮与 Update on reload 的区别：根据 Chrome 的文档，“Update” 执行一次性更新检查，而“Update on reload”会在每次页面加载时强制更新。 两者都不是“重新注册”控件——如果某个 Worker 看起来卡住了，面板自身提供的 控制项只有 Update 和 Unregister，并没有单独的“重新注册”操作。
• Worker 卡在“waiting”状态：根据 Chrome 的文档，Service Workers 面板中 的更新周期表可以显示 Worker 的 install、wait、activate 活动——可以用它 查看 Worker 卡在哪个阶段。
• Cache Storage 中没有内容：根据 Chrome 的文档，DevTools 可能不会 立即检测到缓存变化；在认定缓存确实为空之前，先重新加载页面。
• 离线回退页面未出现：检查 Service Workers 面板中 Source 行旁边的 错误计数——Chrome 的文档说明 Service Worker 错误会显示在那里。

实用检查清单

• 在排查其他问题之前，先检查 Manifest 面板的 Installability 区块中 是否有 manifest/图标错误。
• 开发时使用“Update on reload”，强制每次页面加载都进行更新检查。
• 使用“Bypass for network”比较有无 Service Worker 参与时的行为差异。
• 使用 Clear Storage 在测试运行之间重置 Service Worker、缓存与存储。
• 用 Offline 复选框验证离线回退页面；如果未出现，检查 Service Workers 面板中 Source 行旁边的错误计数。

下一步

• 调试 Service Worker —— 了解 更多跨浏览器检查 Service Worker 的方法
• 更新流程与 skipWaiting
• 缓存策略