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 项目根本不存在该事件。
立即学习“前端免费学习笔记（深入）”；
- 正确监听方式应放在
<script>标签中（非 DOMReady），且确保 DOM 尚未渲染完成前就注册：
<script>
if ('applicationCache' in window) {
const cache = window.applicationCache;
cache.addEventListener('error', () => console.error('AppCache error'));
cache.addEventListener('updateready', () => {
if (cache.status === cache.UPDATEREADY) {
cache.swapCache();
location.reload();
}
});
}
</script>
- 注意：
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”，而是确认你是否还在维护一个已被浏览器集体放弃的技术栈——如果是，迁移比调试更值得投入时间。
