Workbox预缓存策略中如何动态替换版本号导致资源无法更新？

a'ゞ馨月提问于 2026-02-04 00:43:30 阅读 221

移动

在使用Workbox的precacheAndRoute时，我尝试通过环境变量动态替换资源版本号，但发现旧版本资源始终没有被清除，新版本资源也无法更新。配置文件里用了占位符替换，构建时用gulp处理过，但控制台还是显示旧版本的缓存。

比如在workbox-config.js里这样配置：


precacheAndRoute: {
  globPatterns: ['dist/*'],
  substitutions: {
    '/static/': '/static/v{{VERSION}}/'
  }
}

然后在gulp任务里用字符串替换的方式把{{VERSION}}换成实际版本号。但部署后发现浏览器缓存里还是旧的/static/v1.0.0/style.css，新版本的v1.0.1文件完全没有被缓存，这是哪里出问题了？

PWA移动 Workbox

我来解答赞 17 收藏

反馈

2 条解答

美含酱~ Lv1

你这个问题的核心在于Workbox的预缓存机制和版本号替换的实现方式。先说结论：问题出在substitutions配置的使用方式上，它并不能动态更新缓存清单。

Workbox的precacheAndRoute依赖于一个生成的缓存清单文件，这个文件记录了所有需要预缓存的资源及其对应的哈希值。如果你只是通过Gulp替换了{{VERSION}}占位符，但没有同步更新缓存清单文件的内容，那么Workbox在运行时还是会按照旧的清单去缓存资源，导致新版本资源无法生效。

正确的做法是确保每次构建时，缓存清单文件能正确反映新版本资源的变化。推荐的方式是直接在构建过程中动态生成带有版本号的资源路径，并让Workbox重新生成新的缓存清单。以下是具体的调整方案：

首先，在workbox-config.js里去掉substitutions这种容易出问题的配置，改为明确指定资源路径：



module.exports = {

  globDirectory: 'dist/',

  globPatterns: ['**/*.{html,js,css}'],

  swDest: 'dist/sw.js',

};

然后，在Gulp任务中，确保每次构建时都重新生成Workbox配置并调用workbox-build模块来生成服务工作线程文件。比如这样写：



const gulp = require('gulp');

const replace = require('gulp-replace');

const workboxBuild = require('workbox-build');



gulp.task('build', function() {

  const version = 'v1.0.1'; // 动态获取版本号

  return gulp.src('dist/**/*')

    .pipe(replace('/static/', /static/${version}/))

    .pipe(gulp.dest('dist'))

    .on('end', () => {

      workboxBuild.generateSW({

        globDirectory: 'dist/',

        globPatterns: ['**/*.{html,js,css}'],

        swDest: 'dist/sw.js',

      }).then(() => {

        console.log('Service worker generated.');

      });

    });

});

这里的关键点是，每次构建时都会重新生成服务工作线程文件sw.js，并且它会包含最新的资源路径和哈希值。这样可以确保浏览器在安装新的服务工作线程时，能够正确缓存新版本的资源。

最后提醒一句，JS里面的缓存管理有时候真的很让人抓狂，尤其是当你发现明明改了代码但浏览器还是用旧文件的时候。建议你在开发阶段把skipWaiting和clientsClaim都打开，避免调试时被缓存坑到。

2026-02-15 08:08

玉娟 ☘︎ Lv1

你这个情况我遇到过，问题出在 Workbox 的预缓存机制上。precacheAndRoute 会根据资源的 URL 生成缓存键（cache key），如果你只是替换了 URL 中的版本号，但旧的缓存没有清除，Service Worker 仍然会继续使用旧的缓存，直到它被主动清理或者缓存策略触发更新。

关键点有几个：

1. **Service Worker 的更新机制不是实时的**
SW 只有在检测到脚本内容有变化时才会更新，所以你构建时生成的 precache-manifest 如果没有变化，SW 就不会重新缓存资源。

2. **缓存名称默认是固定的**
Workbox 默认的缓存名是 workbox-precache-，不会因为你改了资源 URL 就自动清空旧缓存。

### 解决办法

你有两个选择：

#### ✅ 方法一：给缓存加个版本前缀

在 workbox-config.js 里加上：

module.exports = {

  // ...其他配置

  runtimeCaching: [{

    handler: 'CacheFirst',

    urlPattern: /static/vd+.d+.d+//,

    options: {

      cacheName: 'static-resources-v1.0.1', // 这里直接指定新版本

      expiration: {

        maxEntries: 50,

        maxAgeSeconds: 30 * 24 * 60 * 60 // 30天

      }

    }

  }]

};

这样你每次更新版本号就可以换个缓存名，避免冲突。

#### ✅ 方法二：强制清掉旧缓存

在 Service Worker 初始化的时候手动清缓存：

self.addEventListener('install', (event) => {

  event.waitUntil(

    caches.delete('workbox-precache-https://yourdomain.com/sw.js').then(() => {

      console.log('旧缓存已清除');

    })

  );

});

你也可以更暴力一点，在 activate 事件里清所有缓存（性能上有点重，不推荐）：

self.addEventListener('activate', (event) => {

  event.waitUntil(

    caches.keys().then((keys) => Promise.all(

      keys.map((key) => caches.delete(key))

    ))

  );

});

---

### 总结

Workbox 的 pre-cache 不会自动处理缓存版本切换，你要么换缓存名，要么手动删缓存，否则浏览器会一直用旧缓存。性能上来看，第一种加版本缓存名是最轻量、最推荐的做法，也能避免用户加载旧资源。

2026-02-04 04:33