從 sw-precache 或 sw-toolbox 遷移

先前曾使用 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,
    },
  },
}],

已淘汰的選項

不再支援 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 節點模組

開發人員可使用 node API 為 sw-precache 進行遷移，無論是作為 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 提供的服務工作站等同的服務。

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 上提出問題，讓我們瞭解實際狀況。