HTML5框架离线缓存怎么配置_manifest文件编写指南【说明】

HTML5 manifest文件已被主流浏览器废弃，因AppCache存在设计缺陷且不可控；应改用Service Worker实现可控离线缓存，需HTTPS、正确注册及自定义缓存策略。

HTML5 的 manifest 文件早已被现代浏览器废弃，不建议在新项目中配置或使用。Chrome 从 94 版本起完全移除支持，Firefox 和 Safari 更早停止维护。所谓“离线缓存”实际指 Application Cache（AppCache）机制，它存在设计缺陷、更新不可控、缓存替换逻辑反直觉等问题。

为什么 manifest 文件现在基本不能用

AppCache 被移除不是偶然：

• manifest 文件必须由服务器返回 text/cache-manifest MIME 类型，Nginx/Apache 配置稍有遗漏就彻底失效
• 哪怕只改一个空格，整个缓存会重新下载——但用户刷新页面时仍可能看到旧资源（因为页面本身也被缓存了）
• 没有 API 控制更新时机，window.applicationCache 已从 DOM 接口中删除
• 离线时无法区分“资源未缓存”和“网络故障”，错误处理几乎不可控

替代方案：用 Service Worker 实现真正可控的离线能力

Service Worker 是当前标准，支持精细缓存策略、版本控制、后台同步等。关键点：

• 必须通过 HTTPS（或 localhost）注册，否则 navigator.serviceWorker.register() 直接失败
• 注册代码需放在页面加载完成前，且仅执行一次：

  if ('serviceWorker' in navigator) {
    window.addEventListener('load', () => {
      navigator.serviceWorker.register('/sw.js').catch(err => console.error('SW reg failed:', err));
    });
  }

• sw.js 中用 caches.open() + cache.addAll() 预缓存核心资源，用 fetch 事件拦截请求并返回缓存或网络响应
• 更新逻辑由开发者控制：修改 sw.js 文件内容 → 浏览器下载新脚本 → 触发 install 事件 → 新 SW 进入 waiting 状态 → 调用 skipWaiting() 或关闭所有页面后激活

如果必须兼容老系统（如定制化内嵌 WebView），manifest 文件怎么写才勉强可用

仅限存量维护场景，且确认目标环境（如旧版 Android WebView）仍支持 AppCache：

• 文件名必须为 .appcache 或 .manifest，且服务器需返回正确 MIME：AddType text/cache-manifest .appcache（Apache）
• 第一行必须是 CACHE MANIFEST，大小写敏感，前面不能有空格或 BOM
• 资源路径全部为相对路径，且必须与 manifest 文件同源；绝对路径、跨域资源会被忽略
• NETWORK: 下声明的路径不会被缓存，但若离线访问这些路径，仍会触发 online 事件失败，而非降级到缓存
• 常见陷阱：FALLBACK: 条目第二项必须是已缓存资源，否则整个 fallback 规则失效

CACHE MANIFEST
# v1.2 — 修改此注释才能触发更新
CACHE:
/index.html
/css/app.css
/js/main.js
NETWORK:
/api/
FALLBACK:
/ /offline.html

AppCache 的根本问题在于“缓存即绑定”，而 Service Worker 的核心是“请求可编程”。真正需要离线能力时，绕过 manifest 直接落地 Service Worker，比修复一堆缓存失效问题更省时间。