# 调试 PWA

> 如何使用 Chrome DevTools 的 Application 面板——Manifest、Service Workers、Cache Storage——在开发过程中检查并排查 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** 行旁边。

```js
// 在依赖 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](/zh/reference/service-worker/debugging/) —— 了解
  更多跨浏览器检查 Service Worker 的方法
- [更新流程与 skipWaiting](/zh/reference/service-worker/update-skipwaiting/)
- [缓存策略](/zh/reference/service-worker/caching-strategies/)