17370845950

HTML5 manifest 已被所有主流浏览器弃用，Chrome 78+、Firefox 85+ 禁用，Safari 从未完整支持；其设计缺陷致缓存不透明、无法增量更新、无版本控制，W3C 已移除标准；应改用 Service Worker 实现可控离线能力。

HTML5 manifest 已被所有主流浏览器弃用，不能用于新项目。Chrome 从 78 版本起彻底移除支持，Firefox 在 85 版本中禁用，Safari 从未完整实现。你现在配置的 manifest 文件不会生效，且可能引发控制台警告甚至阻断资源加载。

为什么 manifest 不再可用

该机制存在严重设计缺陷：缓存更新逻辑不透明、主文档与资源缓存绑定过死、无法按需更新单个资源、缺乏版本控制和回滚能力。W3C 已将其从 HTML 标准中删除，取而代之的是更可控、更灵活的 Service Worker。

• manifest 要求服务器返回 text/cache-manifest MIME 类型，现代服务器默认不配置，容易导致离线失败
• 只要 manifest 文件内容有任意字节变化（包括注释或空格），整个缓存就会被丢弃并重新下载——无法增量更新
• 页面首次访问时若网络不可用，即使已有缓存，也会直接显示空白或“无法连接”（取决于浏览器）
• 没有运行时 API，无法监听缓存状态、触发更新、或在 JS 中主动清除

替代方案：用 Service Worker 实现可靠离线访问

这是目前唯一被标准支持、可精确控制缓存行为的方案。核心是注册一个 service-worker.js，并在其中监听 install 和 fetch 事件。

基础示例（保存为 service-worker.js，与页面同域）：

const CACHE_NAME = 'my-site-v1';
const urlsToCache = [
  '/',
  '/index.html',
  '/styles/main.css',
  '/scripts/app.js'
];

self.addEventListener('install', event => {
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then(cache => cache.addAll(urlsToCache))
  );
});

self.addEventListener('fetch', event => {
  event.respondWith(
    caches.match(event.request)
      .then(response => response || fetch(event.request))
  );
});

• 必须通过 HTTPS（或 localhost）提供服务，否则 navigator.serviceWorker.register() 会静默失败
• 注册代码需放在页面 JS 中：navigator.serviceWorker.register('/service-worker.js')
• 首次访问不会触发 install，需刷新一次才能启用缓存；后续访问才真正离线可用
• 更新 service-worker.js 文件内容后，浏览器会在下次访问时拉取新脚本并触发新 install，但旧缓存仍保留，需手动清理或在 activate 阶段删除旧缓存

常见误配与排查点

很多开发者以为改完 manifest 就能离线，结果白忙一场。以下问题在 Service Worker 中更易定位和修复：

• 控制台报错 Uncaught (in promise) TypeError: Failed to register a ServiceWorker → 检查是否 HTTPS / 路径是否正确 / 文件是否存在 404
• 资源仍走网络请求 → 打开 DevTools > Application > Service Workers，确认已激活，并勾选 “Update on reload”；检查 caches.match() 是否匹配到请求 URL（注意路径大小写、尾部斜杠）
• 修改了 HTML 却没更新 → index.html 必须显式加入 urlsToCache，否则永远读取旧缓存
• 想让 API 请求也离线 → fetch 事件中需单独判断 event.request.destination === 'document' 或 event.request.method === 'GET'，避免缓存 POST 请求

真正的离线能力不是加个文件就能实现的，它依赖对缓存生命周期、网络降级策略和用户场景的持续权衡。别再找 manifest 的配置教程了——那条路已经封死了。