之前使用过 sw-precache
和/或 sw-toolbox
的开发者可以通过直接的 Workbox 库系列升级路径。升级到 Workbox 将提供现代化、可扩展的 Service Worker 体验,同时改善调试和开发者工效学设计。
对现有配置的修改
如果您使用的是配置了以下任何选项的 sw-precache
,则在迁移到 Workbox 时,需要考虑以下更改。
已重命名的选项
dynamicUrlToDependencies
配置参数已重命名为 templatedURLs
。
staticFileGlobs
配置参数已重命名为 globPatterns
。
runtimeCaching
配置参数接受一组更新后的选项,与底层 Workbox 模块中使用的名称相对应。为便于说明这些已重命名的内容,此 sw-precache
配置如下所示:
runtimeCaching: [{
urlPattern: /api/,
handler: 'fastest',
options: {
cache: {
name: 'my-api-cache',
maxEntries: 5,
maxAgeSeconds: 60,
},
},
}],
等同于以下 Workbox 配置:
runtimeCaching: [{
urlPattern: /api/,
// 'fastest' is now 'StaleWhileRevalidate'
handler: 'StaleWhileRevalidate',
options: {
// options.cache.name is now options.cacheName
cacheName: 'my-api-cache',
// options.cache is now options.expiration
expiration: {
maxEntries: 5,
maxAgeSeconds: 60,
},
},
}],
已废弃的选项
Express 样式通配符路由不再受支持。如果您在 runtimeCaching
配置中或直接在 sw-toolbox
中使用 Express 样式的通配符路由,请在使用 Workbox 时迁移到等效的正则表达式路由。
sw-precache 迁移
从 sw-precache CLI 到 workbox-cli
对于使用 sw-precache
命令行界面的开发者,无论是手动运行该命令,还是在基于 npm scripts
的构建流程中运行该命令,workbox-cli
模块都是最简单的迁移方式。安装 workbox-cli
后,您就能访问名为 workbox
的二进制文件。
虽然 sw-precache
CLI 支持通过命令行标志或配置文件进行配置,但 workbox
CLI 要求使用 CommonJS module.exports
在配置文件中提供所有配置选项。
workbox
CLI 支持多种不同的模式。(使用 workbox --help
可查看所有通知。)但与 sw-precache
的功能最匹配的模式是 generateSW
。因此,对
$ sw-precache --config='sw-precache-config.js'
可以表示为
$ workbox generateSW workbox-config.js
从 sw-precache 节点模块到 workbox-build 节点模块
无论是在 gulp
/Grunt
工作流中,还是仅在自定义 node
build 脚本中使用适用于 sw-precache
的 node
API,开发者都可以通过切换到 workbox-build
node
模块进行迁移。
workbox-build
模块的 generateSW()
函数与 sw-precache
模块的 write()
函数最为匹配。一个关键区别在于,generateSW()
始终返回 Promise,而旧的 write()
函数同时支持回调和基于 Promise 的接口。
gulp
的使用说明
const swPrecache = require('sw-precache');
gulp.task('generate-service-worker', function () {
return swPrecache.write('service-worker.js', {
// Config options.
});
});
可以更改为
const workboxBuild = require('workbox-build');
gulp.task('generate-service-worker', function () {
return workboxBuild.generateSW({
// Config options.
});
});
从 sw-precache-webpack-plugin 到 Workbox webpack 插件
在 Webpack 构建流程中使用 sw-precache-webpack-plugin
的开发者可以通过切换到 workbox-webpack-plugin
模块中的 GenerateSW
类来进行迁移。
workbox-webpack-plugin
直接与 webpack 构建流程集成,并“了解”给定编译生成的所有资源。这意味着,在许多用例中,您可以依赖 workbox-webpack-plugin
的默认行为,而无需进行额外的配置,并获得与 sw-precache-webpack-plugin
提供的等效 Service Worker。
const SWPrecacheWebpackPlugin = require('sw-precache-webpack-plugin');
const webpackConfig = {
// ...
plugins: [
new SWPrecacheWebpackPlugin({
dontCacheBustUrlsMatching: /\.\w{8}\./,
filename: 'service-worker.js',
}),
],
};
可以更改为
const {GenerateSW} = require('workbox-webpack-plugin');
const webpackConfig = {
// ...
plugins: [
new GenerateSW({
// Config options, if needed.
}),
],
};
sw-toolbox 迁移
从手动设计的 sw-toolbox 迁移到 workbox-sw
如果您直接使用 sw-toolbox
(而不是通过 sw-precache
的 runtimeCaching
选项隐式使用),则迁移到 Workbox 需要一些手动调整才能实现等效的行为。如需了解更多背景信息,请参阅 workbox-routing
和 workbox-strategies
模块的文档,以便提供更多背景信息。
以下是一些有助于指导迁移的代码段。此 sw-toolbox
代码:
importScripts('path/to/sw-toolbox.js');
// Set up a route that matches HTTP 'GET' requests.
toolbox.router.get(
// Match any URL that contains 'ytimg.com', regardless of
// where in the URL that match occurs.
/\.ytimg\.com\//,
// Apply a cache-first strategy to anything that matches.
toolbox.cacheFirst,
{
// Configure a custom cache name and expiration policy.
cache: {
name: 'youtube-thumbnails',
maxEntries: 10,
maxAgeSeconds: 30,
},
}
);
// Set a default network-first strategy to use when
// there is no explicit matching route:
toolbox.router.default = toolbox.networkFirst;
等效于以下 Workbox 代码:
importScripts('path/to/workbox-sw.js');
workbox.routing.registerRoute(
// Match any URL that contains 'ytimg.com'.
// Unlike in sw-toolbox, in Workbox, a RegExp that matches
// a cross-origin URL needs to include the initial 'https://'
// as part of the match.
new RegExp('^https://.*.ytimg.com'),
// Apply a cache-first strategy to anything that matches.
new workbox.strategies.CacheFirst({
// Configuration options are passed in to the strategy.
cacheName: 'youtube-thumbnails',
plugins: [
new workbox.expiration.ExpirationPlugin({
maxEntries: 10,
maxAgeSeconds: 30,
}),
// In Workbox, you must explicitly opt-in to caching
// responses with a status of 0 when using the
// cache-first strategy.
new workbox.cacheableResponse.CacheableResponsePlugin({
statuses: [0, 200],
}),
],
})
);
// Set a default network-first strategy to use when
// there is no explicit matching route:
workbox.routing.setDefaultHandler(new workbox.strategies.NetworkFirst());
获取帮助
我们预计大多数情况下都能轻松迁移到 Workbox。如果您遇到本指南未涵盖的问题,请在 GitHub 上提交问题告诉我们。