如何通过 Content Indexing API 提升 PWA 应用在离线时的内容可见性-js教程-PHP中文网

content indexing api 仅将已缓存的页面注册到浏览器离线界面供用户发现，不负责缓存、下载或保障离线可用；其生效前提是 service worker 已成功缓存对应 url 且响应状态为 200。

如何通过 content indexing api 提升 pwa 应用在离线时的内容可见性

Content Indexing API 本身不提升离线内容可见性——它只让已缓存的资源在浏览器「最近访问」或「离线页面」中被系统索引展示，但不负责缓存、不触发下载、不保证离线可用。真正决定离线能否看到内容的，是 Service Worker + Cache API 是否已把对应资源存进缓存。

`Content Indexing API` 的真实作用场景

用户在 Chrome（仅支持）中打开「历史记录」→「已保存的页面」，或进入「设置 → 离线页面」列表时，能看到你注册过的标题、描述和图标
它只是把已存在的缓存条目“打标”并暴露给系统 UI，类似给缓存文件加了个目录索引
不会自动拉取新内容，也不会在用户没访问过某页时提前索引它

常见误判：以为调用 index.add() 就等于“缓存了该页面”，实际它只报错或静默失败，如果对应 URL 根本没进过 caches

如何正确配合缓存使用 `Content Indexing API`

确保三件事严格按顺序发生：

Service Worker 已安装并激活，且至少一次成功缓存了目标页面（如 /article/123）
页面响应状态码是 200（非重定向、非 404），且响应头包含 content-type: text/html
在 activate 或 fetch 后的稳定时机调用索引（不能在 install 阶段，此时缓存可能未就绪）

self.addEventListener('activate', event => {
  event.waitUntil((async () => {
    const cache = await caches.open('pages-cache-v1');
    const response = await cache.match('/article/123');
    if (response && response.status === 200) {
      const registration = await navigator.serviceWorker.getRegistration();
      if ('index' in registration) {
        await registration.index.add({
          id: 'article-123',
          url: '/article/123',
          title: '如何调试 Service Worker',
          description: '详解 fetch 事件拦截与缓存匹配逻辑',
          icons: [{ src: '/icons/article-123.png', sizes: '192x192', type: 'image/png' }]
        });
      }
    }
  })());
});

容易踩的坑

navigator.index 在主线程不可用，必须通过 registration.index 调用（且需先获取 registration）
Chrome 仅在「桌面版」和「Android Chrome 85+」支持，iOS/Safari 完全不支持，别在 manifest 或 install 里硬依赖
索引条目不会随缓存自动更新：缓存了新版本 HTML，但没重新 index.add()，系统仍显示旧标题和描述
url 必须与缓存中的请求 URL 完全一致（含查询参数），/post?id=1 和 /post/?id=1 被视为不同条目

Content Indexing API 是个“锦上添花”的能力，不是离线兜底方案。真正关键的，永远是 caches.match() 能否命中、fetch() 拦截是否可靠、以及 offline.html 是否被 fallback 正确兜住。索引只是让用户更容易从系统入口找回那个已存在的离线页面。