从 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,
    },
  },
}],

已废弃的选项

不支持快捷方式风格的通配符路线。如果您在 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 脚本中使用 node API 来处理 sw-precache，则可以通过切换到 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 上提交问题告知我们。