Content Indexing API 仅将已缓存的页面注册到浏览器离线界面供用户发现，不负责缓存、下载或保障离线可用；其生效前提是 Service Worker 已成功缓存对应 URL 且响应状态为 200。
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 正确兜住。索引只是让用户更容易从系统入口找回那个已存在的离线页面。
