17370845950

HTML5 的 Application Cache（manifest）机制已被主流浏览器废弃，缓存失败主因是技术淘汰而非配置错误；需改用 Service Worker + Cache API 或 Workbox 实现现代离线能力。

HTML5 本身不“安装”，所谓“安装 HTML5 后缓存失败”实际是指基于 Application Cache（即 manifest）的离线缓存机制配置或运行出错——而这个机制在现代浏览器中已被废弃，Chrome 94+、Firefox 85+、Safari 16.4+ 均已彻底移除支持。所以，如果你在新项目中遇到“缓存失败”，大概率不是配置问题，而是技术路线已失效。

manifest 文件抓取失败（-1）：MIME 类型没配对

这是最常见且最容易被忽略的硬性门槛。浏览器只认 text/cache-manifest 类型的响应头，哪怕文件内容完全正确，只要服务器返回的是 text/plain 或 application/octet-stream，就会直接报错 “清单提取失败(-1)”。

• Apache：在 .htaccess 或 mime.types 中添加 AddType text/cache-manifest .appcache 或 AddType text/cache-manifest .manifest
• Nginx：在 server 块内加 types { text/cache-manifest appcache; }
• Python http.server：需自定义 handler，原生 SimpleHTTPServer 不支持，推荐改用 python -m http.server --bind 127.0.0.1:8000 并配合 serve 工具或轻量 Node 服务（如 http-server -c-1）
• 本地双击打开 HTML 文件（file:// 协议）必然失败——AppCache 要求 HTTP/HTTPS 协议

CACHE MANIFEST 文件格式错误：空格、换行、路径全都是雷

Manifest 解析极其脆弱，任何格式偏差都会导致整个缓存流程中断，且错误静默（控制台可能只报 -1，不提示哪一行错）。

• CACHE MANIFEST 必须是文件第一行，前面不能有 BOM、空行、注释或空格
• 每行末尾不能有多余空格（包括 Windows 换行符 \r\n 后的不可见空格）
• 路径必须为相对路径（相对于 manifest 文件所在位置），且区分大小写；Scripts/script.js 和 scripts/script.js 是两个资源
• 禁止出现 PHP/ASP/JSP 等动态文件（如含 header("Location:") 或重定向逻辑），它们无法被缓存，且会阻断后续所有资源下载
• 禁止在缓存列表中写入跨域资源（如 http://code.jquery.com/...），除非服务器明确允许 CORS 且 manifest 本身也托管在同一域下

事件监听没生效或时机错乱：mobileinit 不是万能钥匙

很多教程教你在 mobileinit 里绑定 window.applicationCache 事件，但这仅适用于 jQuery Mobile 早期版本，且前提是页面已加载 jQuery Mobile 库——纯 HTML5 项目根本不存在该事件。

• 正确监听方式应放在 标签中（非 DOMReady），且确保 DOM 尚未渲染完成前就注册：

• 注意：swapCache() 不会自动刷新页面，必须手动 location.reload()；否则用户看到的仍是旧缓存
• Safari 对 document.location = 'xxx' 类跳转极其敏感，会导致缓存中止，需包裹 setTimeout 延迟执行

为什么现在不该再用 AppCache？替代方案更可靠

AppCache 设计存在根本缺陷：缓存更新逻辑反直觉（更新 manifest 才触发全量重下）、无细粒度控制、强制全站缓存、不支持条件缓存、与 Service Worker 不兼容。所有主流浏览器已将其标记为 Deprecated 并最终移除。

• 新项目请直接使用 Service Worker + Cache API，它支持按需缓存、版本化控制、网络优先/缓存优先策略、后台同步等
• 若需快速落地离线能力，可用 Workbox（Google 官方封装库），几行配置即可生成健壮缓存策略
• 静态站点可搭配 Web App Manifest（manifest.json）实现“添加到主屏幕”和基础启动体验，但它不负责资源缓存

真正关键的不是“怎么修 manifest”，而是确认你是否还在维护一个已被浏览器集体放弃的技术栈——如果是，迁移比调试更值得投入时间。