17370845950

HTML5 AppCache 清单文件需满足四点：MIME 类型为 text/cache-manifest；manifest 属性用绝对路径；清单首行为 CACHE MANIFEST 且路径严格匹配；仅清单内容变更才触发更新；该技术已被现代浏览器弃用，建议迁移到 Service Worker。

清单文件 MIME 类型必须是 text/cache-manifest

浏览器只在响应头包含 Content-Type: text/cache-manifest 时才识别 manifest 文件。常见错误是 Web 服务器（如 Nginx、Apache）未配置该类型，导致即使文件存在、路径正确，浏览器也直接忽略缓存声明。

实操建议：

• Nginx 中添加：types { text/cache-manifest manifest; }，并在 location 块中确保 add_header Content-Type text/cache-manifest;（或更稳妥地用 default_type text/cache-manifest;）
• Apache 中在 .htaccess 或虚拟主机配置里加：AddType text/cache-manifest .manifest（注意扩展名要匹配，比如你用的是 cache.manifest 就得写 .manifest）
• 用 curl -I https://yoursite.com/cache.manifest 检查响应头，确认 Content-Type 确实为 text/cache-manifest，不是 text/plain 或 application/octet-stream

html 标签的 manifest 属性路径必须绝对且可访问

Manifest 路径不是相对 HTML 文件位置解析的，而是相对于页面 URL 的根路径（即以 / 开头），且浏览器会发起一次独立 HTTP 请求获取它——若 404、重定向或跨域，都会静默失败。

实操建议：

• 检查 HTML 中是否写成 （错误：相对路径易出错）→ 应改为
• 在浏览器开发者工具的 Network 面板中过滤 manifest，确认请求状态码是 200，且响应体开头是 CACHE MANIFEST（必须全大写、顶格、无 BOM）
• 避免使用查询参数，如 /cache.manifest?v=1.2 —— 多数浏览器不支持带 query 的 manifest URL

清单内容格式错误：空行、注释、路径大小写与实际资源不一致

Manifest 解析极其严格：首行必须是 CACHE MANIFEST；所有资源路径必须与服务器实际返回的路径完全一致（含大小写、尾部斜杠、查询参数）；空行或非法字符会导致整个清单被丢弃。

实操建议：

• 用文本编辑器确认文件编码为 UTF-8 无 BOM；首行仅 CACHE MANIFEST，前后无空格、不可见字符
• 清单中列出的每个资源（如 script.js、/styles/main.css）都应在 Network 面板中手动访问一次，验证返回状态码和实际路径是否与清单中**逐字相同**
• 禁止在 CACHE 段写动态路径（如 api/data.json），除非你明确用 NETWORK: 段放行；否则浏览器会尝试缓存它并失败
• 常见陷阱：开发环境用 localhost，但清单里写了 https://prod.example.com/image.png → 跨域不被允许，直接跳过

更新机制失效：浏览器只在清单文件内容变化时触发重缓存

Manifest 不会因引用的 JS/CSS 文件更新而自动刷新；只有 manifest 文件自身内容（哪怕只改一个空格或注释）发生变化，浏览器才会重新下载并切换缓存版本。

实操建议：

• 在清单末尾加注释行作为版本标记：# v2.1.5-20250612，每次发布前手动或脚本更新该行
• 不要依赖时间戳自动生成（如 # ），服务端渲染会导致每次响应不同，破坏离线可用性
• 调试时可在控制台执行 window.applicationCache.swapCache() 强制应用新缓存（需先触发 updateready 事件）；但注意：现代浏览器已废弃此 API，仅用于遗留系统验证

HTML5 Application Cache 已被标准弃用，Chrome 95+、Firefox 85+ 默认禁用，Safari 从 iOS 15.4 开始移除支持。如果项目仍在用，排查务必紧扣这四点；若新建项目，请直接转向 Service Worker + Cache API 方案——manifest 的容错率低、调试链路长，很多失败根本不会报错，只默默走网络回退。