先前曾使用 sw-precache
和/或 sw-toolbox
的開發人員,對 Workbox 系列程式庫的升級路徑有直觀的升級路徑。升級至 Workbox 將提供現代化的可擴充性服務工作人員體驗,包括改善偵錯能力和開發人員人體工學。
修改現有設定
如果您使用的 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,
},
},
}],
已淘汰的選項
不再支援速成式萬用字元路徑。如果您在 runtimeCaching
設定或直接使用 sw-toolbox
中使用快速樣式萬用字元路徑,請在使用 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 節點模組
如果開發人員使用 sw-precache
適用的 node
API,不論是在 gulp
/Grunt
工作流程中,或只在自訂 node
建構指令碼中,都可以改用 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 遷移至工作箱
如果您直接使用 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 開啟問題回報給我們。