从 sw-precache 或 sw-toolbox 迁移

之前使用过 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 上提交问题告诉我们。