manifest 文件必须以 text/cache-manifest MIME 类型返回，且需严格遵循语法规范：首行 CACHE MANIFEST、区分大小写的节标题、路径全小写并含查询参数；HTML 中 manifest 属性须置于 <html> 标签且路径相对正确；更新需字节级变更并禁用缓存。
manifest 文件必须用正确的 MIME 类型返回
浏览器只在响应头包含 Content-Type: text/cache-manifest 时才识别 .manifest 文件。Apache 默认不支持该类型，Nginx 也不会自动设置。如果只是把文件丢进目录，服务器返回 text/plain 或 application/octet-stream，整个离线功能就静默失效——没有报错，但资源不会被缓存。
实操建议：
- Apache：在
.htaccess或虚拟主机配置中添加AddType text/cache-manifest .manifest - Nginx：在
server块中加入types { text/cache-manifest manifest; } - 开发阶段用本地服务器（如
python3 -m http.server）时，它不支持自定义 MIME，必须换用serve、http-server或起个轻量 Node 服务
HTML 中的 manifest 属性必须写在 <html> 标签上且路径正确
manifest 是 <html> 元素的专属属性，写在 <head> 或其他标签里无效；路径也必须是相对 HTML 文件的路径，不是相对于域名根目录。
常见错误现象：页面刷新后仍联网加载、F12 的 Application → Cache Storage 为空、控制台无相关日志。
立即学习“前端免费学习笔记（深入）”；
实操建议：
- 确保写法为
<html manifest="app.manifest">，不是manifest="./app.manifest"或manifest="/app.manifest"（除非 HTML 确实在根目录） - 如果 HTML 在
/sub/page.html，而app.manifest和它同级，则写manifest="app.manifest"；若 manifest 在/sub/cache/app.manifest，则写manifest="cache/app.manifest" - 不要用 HTTPS 页面引用 HTTP 的 manifest（混合内容会被现代浏览器直接拒载）
manifest 文件语法有严格格式要求，空行和注释不能乱放
manifest 文件不是普通文本，首行必须是 CACHE MANIFEST（大小写敏感），之后每行要么是资源路径、要么是 # 开头的注释、要么是空行。开头多一个 BOM、第一行缩进、或写成 cache-manifest 都会导致解析失败。
示例正确结构：
CACHE MANIFEST # v1.2 - updated 2024-06-15 <p>CACHE: /index.html /style.css /app.js</p><p>NETWORK: /api/</p><ul><li></li></ul><p>FALLBACK: / /offline.html
关键细节：
-
CACHE:、NETWORK:、FALLBACK:是区分大小写的节标题，冒号后必须跟换行或空格 -
*在NETWORK:节中表示“除已声明外所有网络请求”，但它不能出现在CACHE:节 - 路径必须全部小写且与实际 URL 完全一致（包括查询参数：
data.json?v=2和data.json被视为两个不同资源）
更新缓存需要服务端响应头配合，单纯改 manifest 内容不一定触发重载
浏览器只在 manifest 文件内容（字节级）发生变化时才会重新下载整个缓存组。但如果你只改了注释行，而服务器返回了 304 Not Modified（比如 ETag 或 Last-Modified 未变），那这次“变化”就被跳过了。
容易踩的坑：
- 用构建工具自动生成 manifest 时，没强制更新时间戳或哈希值，导致部署新 JS 后缓存不更新
- CDN 缓存了 manifest 文件，即使源站改了，用户仍拿到旧版本
- 本地测试时反复修改 manifest，但没清浏览器缓存或关掉 DevTools 的 “Disable cache” 选项，误以为机制失效
可靠做法：在 manifest 第二行加动态注释，例如 # build: 202406151423，并确保该行随每次构建真实变更；同时给 manifest 响应头加上 Cache-Control: no-cache，避免中间代理干扰。
真正麻烦的是 fallback 和 online/offline 状态判断逻辑——这些不在 manifest 里定义，得靠 window.applicationCache 事件或现代 navigator.onLine 配合 JavaScript 补足。manifest 只管“存什么”，不管“怎么用”。
