17370845950

应改用 Service Worker 替代已废弃的 HTML5 manifest，因其支持按需缓存、动态策略与离线增强能力，而 manifest 静态声明式机制导致体积膨胀、更新失效及重复下载等问题。

manifest 文件体积过大导致首次加载变慢

HTML5 manifest 已被现代浏览器废弃（Chrome 94+ 完全移除），但若你仍在维护旧项目，发现 cache.manifest 文件越来越大、首屏加载卡顿，核心问题不是“怎么压缩 manifest”，而是“不该把所有资源都塞进 CACHE 段”。浏览器会强制下载并缓存 CACHE 下所有条目，哪怕用户只访问首页，也会拖下整个后台 JS、整套图标、未使用的 CSS 组件。

实操建议：

• 把 CACHE 段从“全站兜底”改为“最小可用集”：仅保留 index.html、基础 CSS/JS、首屏必需图片（如 logo、loading 图）
• 将非首屏资源（如后台路由 JS、报表图表库、多语言 JSON）移出 CACHE，改用 NETWORK 段声明为“不缓存”，或彻底删掉该行（默认就是网络请求）
• 避免通配符写法：*.js 或 js/ 会被当作字面量路径，实际不会匹配——manifest 不支持 glob，写了等于白写还增大体积
• 检查是否误把 vendor.js.map、source-map 文件写进了 manifest：这类文件体积大、无运行时价值，必须剔除

用 Service Worker 替代 manifest 实现按需缓存

manifest 是静态声明式缓存，无法动态判断“用户当前需要什么”。Service Worker 可在 fetch 事件中做细粒度控制，比如只缓存用户已访问过的页面、按路由前缀分类缓存策略、甚至结合 navigator.onLine 切换缓存模式。

实操建议：

• 用 workbox.routing.registerRoute() 配合正则，对不同资源类型设置不同缓存策略：

  workbox.routing.registerRoute(
    /\/api\//,
    new workbox.strategies.NetworkFirst()
  );
  workbox.routing.registerRoute(
    /\.(?:js|css|html)$/,
    new workbox.strategies.StaleWhileRevalidate()
  );

• 避免在 install 事件里 cache.addAll() 全量预缓存——这和 manifest 的 CACHE 段一样危险；改用 cache.add() 单个添加关键资源，或留空 install，靠运行时缓存积累
• 使用 workbox.expiration.ExpirationPlugin 控制缓存生命周期，防止缓存无限膨胀（例如限制最多缓存 50 个 HTML 页面，过期时间 7 天）

manifest 中误写相对路径导致重复下载

manifest 文件里的路径是相对于 manifest 自身位置解析的，不是相对于 HTML。如果 cache.manifest 放在根目录，但里面写 js/app.js，而实际 HTML 引用的是 /static/js/app.js，浏览器会把这两个视为不同资源，重复下载且各自缓存一份。

常见错误现象：

• DevTools 的 Application → Cache Storage 里出现多个同名 JS 文件，大小一致但 URL 不同
• 修改 JS 后清缓存重试，页面仍运行旧逻辑

实操建议：

• 统一用绝对路径（以 / 开头）写入 manifest，例如 /js/app.js、/css/main.css
• 确保 manifest 文件中列出的路径与 HTML 中 、 的实际请求 URL 完全一致（包括查询参数，如 ?v=1.2.3）
• 用 curl -I http://yoursite.com/cache.manifest 确认响应头含 Content-Type: text/cache-manifest，否则部分浏览器不识别

缓存更新失效：manifest 文件没变，资源却没更新

manifest 缓存机制依赖“文件内容变更触发更新”。如果只更新了 app.js 但忘了修改 cache.manifest 文件本身（哪怕只加一个空格），浏览器认为 manifest 没变，就不会重新下载和替换缓存。

容易被忽略的点：

• 构建工具（如 Webpack）自动生成 manifest 时，若未将 JS/CSS 文件哈希值写入 manifest，就失去了更新触发能力
• 服务器启用了强缓存（Cache-Control: max-age=31536000）给 cache.manifest，导致浏览器根本不去检查它是否变化
• manifest 文件本身被 CDN 缓存，且未配置 Cache-Control: no-cache 或 ETag 校验

实操建议：

• 在 manifest 文件末尾加注释行，每次构建自动更新时间戳：# version 202505201430
• 给 cache.manifest 设置响应头：Cache-Control: no-cache, must-revalidate
• 避免在 manifest 中直接引用带哈希的文件（如 app.a1b2c3.js），因为哈希变，manifest 必须同步变；更稳妥的是让构建工具生成 manifest 并注入最新哈希值

manifest 的本质缺陷在于“静态不可控”，而真实业务需要的是“用户行为驱动的缓存”。现在花半天迁移到 Service Worker，比花三天调 manifest 的缓存失效逻辑更省时间——尤其当你要支持离线表单提交、后台同步、消息推送时，manifest 连门都摸不到。