HTML5离线应用配置与缓存清单教程

本文深入剖析了HTML5离线应用核心机制——cache.manifest文件的配置要点与常见陷阱，澄清了“必须放根目录”等普遍误解，强调其依赖同源可访问性、严格MIME类型（text/cache-manifest）及零容错的语法规范（如首行全大写、无BOM、注释格式等），同时揭示了开发调试中的致命盲区：file://协议失效、时间戳更新技巧、Chrome/Firefox已全面废弃Application Cache API等现实约束；最终明确指出——manifest技术已被现代浏览器淘汰，当前唯一可行的离线方案是迁移到Service Worker与Cache API，让开发者直面历史兼容性终结与技术升级的迫切需求。

cache.manifest 文件必须放在 Web 服务器根目录吗？

不一定，但绝大多数情况下必须和 HTML 页面同源且可被同域请求到。浏览器只认 manifest 属性指向的路径是否能返回正确 MIME 类型（text/cache-manifest）和格式，不强制要求物理位置，但实际部署中放错位置会导致 404 或 MIME 不匹配——这是离线失败最常见原因。

• manifest 属性值是相对路径，比如 ，那它就相对于当前 HTML 的 URL 解析
• Apache/Nginx 需显式配置 .manifest 后缀返回 text/cache-manifest；否则即使文件存在，Chrome 会静默忽略
• 开发时用 file:// 协议直接双击 HTML 打开，manifest 完全不生效——必须走 HTTP/HTTPS

缓存清单语法写错一行就会整个失效

Manifest 文件不是宽松解析的配置，任何空格、大小写、BOM、注释位置错误都会让浏览器拒绝缓存。尤其注意：首行必须是 CACHE MANIFEST（全大写、无空格、无 BOM），且后面要换行。

• 开头不能有 UTF-8 BOM 字节（用 VS Code 或 Sublime 保存时选 “UTF-8 without BOM”）
• NETWORK: 和 FALLBACK: 是可选节，但一旦出现，冒号后必须换行，不能写成 NETWORK: /api/
• 路径区分大小写，index.html 和 Index.html 被视为两个资源
• 注释只能用 # 开头，且必须独占一行或位于行尾，style.css # 注释 是非法的

CACHE MANIFEST
# v1.2 - 2024-06-15
CACHE:
/index.html
/js/app.js
/css/main.css
<p>NETWORK:
/api/
FALLBACK:
/ /offline.html</p>

HTML 中引用 manifest 后页面没变离线也能访问？

不是“引用即生效”，而是触发一次完整更新周期：首次访问 → 下载并缓存 → 后续访问才可能离线加载。而且浏览器只在检测到 manifest 内容变更（字节级比对）时才会重新下载整个缓存组。

• 修改了 app.js 但没改 manifest 文件内容？浏览器根本不会拉新 JS
• 调试时想强制刷新缓存，可以手动调用 applicationCache.update()（已废弃但旧版仍可用），更可靠的是在 manifest 里加一行带时间戳的注释：# build: 202406151423
• 用户首次访问后关掉网络再刷新，如果页面之前没完整缓存成功（比如某个资源 404），整个缓存组会被丢弃，回退到在线模式（甚至白屏）

Chrome 控制台里看不到 applicationCache 相关日志了？

因为 Chrome 94+ 已彻底移除 applicationCache API 和 DevTools 支持，Firefox 也早在 2022 年禁用。现在看到的“Application → Cache Storage”是 Service Worker 的 Cache API，和旧 manifest 无关。

• 还在用 manifest 的项目，调试只能靠 Network 面板看请求是否 200（来自 disk cache）或 status 显示 from ServiceWorker（说明已被覆盖）
• 真实离线验证必须关 Wi-Fi + 拔网线，不能只靠“Offline”模拟——模拟模式下部分浏览器仍允许读取磁盘缓存
• 移动端 iOS Safari 对 manifest 支持极差，iOS 12+ 已完全移除，Android Chrome 早就不维护，别指望兼容新设备

真正需要离线能力的场景，现在唯一靠谱路径是迁移到 Service Worker + Cache API，manifest 文件本身已经是个历史快照，写得再规范也绕不开浏览器支持终止的事实。

理论要掌握，实操不能落！以上关于《HTML5离线应用配置与缓存清单教程》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！