Content Indexing API 仅声明可索引的离线内容，不管理缓存、不控制导航、不触发离线加载；其作用是将已缓存URL注册到浏览器离线界面，实际离线访问依赖Service Worker的fetch事件正确返回缓存响应。
Content Indexing API 无法引导用户访问离线缓存内容——它只负责向浏览器“声明”有哪些内容可被索引和展示，不参与缓存逻辑、不控制导航、也不触发离线加载。
Content Indexing API 的实际作用范围
这个 API 是浏览器提供给 PWA 的一个元数据注册接口，核心功能是让已缓存的页面（比如通过 Cache API 或 Workbox 缓存的 URL）在「网站设置 → 离线内容」或 Chrome 的 chrome://apps 等界面中显示为可发现项。它本身：
- 不读取、不写入、不验证缓存是否存在
- 不拦截网络请求，也不重写
fetch事件 - 不与
Service Worker的缓存策略自动联动 - 调用
registration.index.add()成功 ≠ 内容已缓存，只是“挂了个名”
真正决定离线能否访问的是 Service Worker + Cache API
用户点击 Content Indexing 列表里的条目后，浏览器会发起一次标准导航请求（GET）。能否成功加载，完全取决于你的 Service Worker 是否在 fetch 事件中正确匹配并返回了缓存响应。常见疏漏包括：
- 缓存时用了带 hash 的文件名（如
main.a1b2c3.js），但index.add()注册的是未 hash 的路径（如/app/），导致匹配失败 -
fetch事件监听器未覆盖导航请求（缺少event.request.mode === 'navigate'判断） - 缓存策略未包含 HTML 文件，或 HTML 缓存过期时间太短，离线时已失效
- 使用了
cache.match(event.request)但没 fallback 到networkFirst或cacheOnly明确策略
如何让索引条目真正导向离线可用内容
必须手动对齐三件事：缓存行为、索引注册、导航响应。示例关键片段：
/* 在 Service Worker 中 */
self.addEventListener('fetch', event => {
if (event.request.mode === 'navigate') {
// 优先尝试匹配 HTML 缓存
event.respondWith(
caches.match(event.request)
.then(resp => resp || fetch(event.request))
);
}
});
<p>// 缓存 HTML 页面（例如在 install 或 message 事件中）
caches.open('pages-v1').then(cache =>
cache.addAll(['/app/', '/app/article-123/', '/app/offline.html'])
);</p><p>// 索引注册必须与缓存路径严格一致
registration.index.add({
id: 'article-123',
url: '/app/article-123/',
title: '离线也能看的文章',
description: '已预缓存',
icons: [{ src: '/icons/icon-192.png', sizes: '192x192', type: 'image/png' }]
});注意：url 字段必须是完整相对路径（以 / 开头），且与 cache.addAll() 或 cache.put() 中使用的 key 完全一致（包括结尾斜杠、查询参数、大小写）。
Chrome 中调试索引与缓存是否对齐
打开 chrome://serviceworker-internals 查看当前注册的 SW；再访问 chrome://apps（需启用 chrome://flags/#enable-desktop-pwas）确认索引是否出现。但更关键的是检查缓存内容：
- F12 → Application → Cache Storage → 展开对应 cache 名称，确认目标 URL 已存在且响应体非空
- 断网后手动访问该 URL，看是否返回 200（来自 service worker）而非 504 或连接失败
- 若索引条目点击后白屏或报错，大概率是
fetch事件里没处理好 HTML 导航，或缓存中根本没有那个 HTML 响应
最常被忽略的一点：Content Indexing API 是“静态声明”，而缓存是“动态行为”。两者不同步时，索引就像一张过期地图——标了位置，但房子早拆了。
