HTML5manifest缓存规则与路径写法详解

在文章实战开发的过程中，我们经常会遇到一些这样那样的问题，然后要卡好半天，等问题解决了才发现原来一些细节知识点还是没有掌握好。今天golang学习网就整理分享《HTML5 manifest缓存列表写法及路径规则详解》，聊聊，希望可以帮助到正在努力赚钱的你。

manifest文件必须以严格大小写的“CACHE MANIFEST”开头，末尾无空格或BOM；路径相对manifest位置解析，推荐用绝对路径；仅NETWORK和FALLBACK支持前缀通配；更新需字节级变更；现代浏览器已废弃，应迁移到Service Worker。

manifest 文件必须以 CACHE MANIFEST 开头

浏览器只认这一行作为合法 manifest 的起始标识，大小写敏感，末尾不能有多余空格或 BOM。如果写成 cache manifest、CACHEMANIFEST 或带 UTF-8 BOM，整个文件会被忽略，且不会报错——资源照常加载，但完全不走离线缓存。

常见误操作：

• 用编辑器保存为 UTF-8 with BOM（尤其是 Windows 记事本）→ 用 file -i your.appcache 检查编码，改用无 BOM 的 UTF-8
• 在第一行前加注释（如 # version 1.2）→ 注释只能放在 CACHE MANIFEST 行之后
• 漏掉换行 → CACHE MANIFESTNETWORK * 这种连写会导致解析失败

CACHE 区块里路径是相对 manifest 文件位置解析的

不是相对于 HTML 页面，也不是相对于域名根目录。比如 index.html 引用了 app.manifest，而 app.manifest 存在 /static/ 下，那么它内部写的 js/main.js 就会被解析为 /static/js/main.js，而非网站根目录下的 /js/main.js。

稳妥做法：

• 统一把 manifest 放在站点根目录（如 /app.manifest），这样路径可直接按站内 URL 写
• 路径尽量用绝对路径（以 / 开头），避免歧义：/css/style.css、/api/config.json
• 不要写协议+域名（https://example.com/logo.png），跨域资源无法被缓存
• 支持通配符仅限于 NETWORK 和 FALLBACK，CACHE 区块不支持 * 或 **

NETWORK 和 FALLBACK 的匹配逻辑容易被误解

NETWORK 是「从不缓存」白名单，但它的通配规则是前缀匹配，不是 glob 或正则。例如写 api/，会匹配 /api/login、/api/v2/data，但不匹配 /public/api/status；写 * 表示所有未显式声明的资源都绕过缓存（即默认网络优先）。

FALLBACK 格式为 online-path fallback-path，注意两点：

• online-path 也按前缀匹配，且必须以 / 开头（如 /pages/ /offline.html）
• fallback-path 必须是已缓存在 CACHE 区块里的资源，否则降级失败，页面直接报 404
• 不支持 query 参数匹配：/data.json?ver=2 和 /data.json 被视为不同资源，后者需单独列在 CACHE 中才能 fallback

HTML 中引用和更新 manifest 的实际影响

通过 启用后，浏览器会在首次加载时下载并解析 manifest，并缓存所有 CACHE 列表资源。但关键点是：**只有 manifest 文件内容发生字节级变化，浏览器才会重新下载整个缓存组**。

所以日常维护要注意：

• 别靠改注释触发更新（如 # v1.0.1）→ 注释不参与比对，必须改非注释行（哪怕加个空格）
• 动态资源（如 /time.php）即使进了 CACHE，每次访问仍可能返回新内容（取决于服务器 Cache-Control），manifest 不保证内容静态性
• 删除某个资源后，旧版本浏览器仍会从缓存返回它，直到用户强制刷新或 manifest 更新且该资源被移出 CACHE
• 现代浏览器（Chrome 95+、Firefox 92+、Safari 16.4+）已废弃 Application Cache，仅部分旧项目或 WebView 场景还需兼容

真正需要离线能力的新项目，请直接用 Service Worker，manifest 机制已不具备演进空间。

到这里，我们也就讲完了《HTML5manifest缓存规则与路径写法详解》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！