HTML文件必须显式列入manifest的CACHE段且路径精确匹配，manifest属性须置于<html>标签首位，MIME类型需为text/cache-manifest，资源加载时序和交互逻辑也需适配离线场景。
manifest 文件必须声明 HTML 页面本身
很多开发者只把 CSS、JS、图片写进 cache 白名单，却漏掉主 HTML 文件——这是首屏无法离线渲染的最常见原因。浏览器离线时不会自动缓存当前访问的 HTML，必须显式列入 manifest 的 CACHE 段。
实操建议：
- 确保
index.html（或你实际的入口文件）出现在CACHE:下第一行，且路径与页面 URL 完全一致（含查询参数差异都会导致匹配失败） - 避免使用动态生成的 HTML 路径（如
/app/?v=1.2.3），manifest 不支持通配符或正则，只做精确字符串匹配 - 如果用构建工具（如 Webpack），需将 HTML 文件作为静态资源输出，并在 manifest 中硬编码其最终路径，例如
/dist/index.html
HTML 必须显式关联 manifest 且位置正确
manifest 属性只能写在 <html> 标签上，且必须是首个属性；放在 <head> 里其他位置（比如 <link rel="manifest">）完全无效——那是给 Web App Manifest 用的，和离线缓存无关。
常见错误现象：页面在线正常，离线后白屏或报 net::ERR_FAILED，但控制台无明显提示。
立即学习“前端免费学习笔记（深入）”；
实操建议：
- 检查 HTML 开头是否为：
<html manifest="/cache.manifest">（注意路径必须可被同源请求到） - manifest 文件 MIME 类型必须是
text/cache-manifest，Nginx 或 Express 需单独配置，否则 Chrome 会静默忽略 - 修改 manifest 后，浏览器不会自动更新缓存——必须更改文件内容（哪怕加个空格），触发版本变更，否则旧 HTML 仍绑定旧资源
首屏按钮依赖的资源必须零延迟可用
即使 HTML 被缓存，按钮若依赖未缓存的 CSS 类、内联样式失效、或 JS 在 window.onload 后才绑定事件，离线时仍会“有结构无交互”。manifest 只解决资源存在性，不解决加载时序。
实操建议：
- 按钮的样式（包括伪类
:active）必须来自已缓存的 CSS，避免使用未声明的 class 或style属性内联写法（内联样式不被 manifest 管理） - 事件监听不能依赖
DOMContentLoaded或load，应直接写在 HTML 中：<button onclick="handleClick()">，或确保初始化脚本位于<head>且已缓存 - 避免在 JS 中动态插入按钮 DOM——离线时执行失败，按钮根本不存在
调试时别信“Application”面板里的缓存状态
Chrome DevTools 的 Application → Manifest 标签页只显示注册状态，不代表资源真被缓存。真正验证方式只有断网后刷新——且必须是硬刷新（Ctrl+F5 或清空缓存后重载），普通刷新可能走内存缓存，掩盖问题。
容易踩的坑：
- 本地 file:// 协议下 manifest 完全不生效，必须通过 HTTP(S) 服务访问
- Service Worker 和 AppCache（manifest）不能共存，启用 SW 后 manifest 会被忽略，而多数现代项目已迁移到 SW
- iOS Safari 对 manifest 支持极差，iOS 12+ 已彻底弃用，仅适用于遗留 Android WebView 或老版桌面 Chrome
如果你的项目需要真正可靠的离线首屏，现在该考虑迁移到 Service Worker + Cache API，manifest 是条死胡同。
