Workbox-webpack-plugin

Workbox 提供了两个 webpack 插件：一个用于为您生成完整的 Service Worker，另一个用于生成要预缓存的资源列表，并将其注入 Service Worker 文件中。

这些插件在 workbox-webpack-plugin 模块中实现为两个类，分别命名为 GenerateSW 和 InjectManifest。回答以下问题有助于您选择要使用的正确插件和配置。

要使用哪个插件

GenerateSW

GenerateSW 插件会为您创建一个服务工作器文件，并将其添加到 webpack 资源流水线。

何时使用 GenerateSW

• 您想预缓存文件。
• 您有简单的运行时缓存需求。

不应使用 GenerateSW 的情况

• 您想使用其他 Service Worker 功能（例如网站推送）。
• 您想要导入其他脚本，或为自定义缓存策略添加其他逻辑。

InjectManifest

InjectManifest 插件将生成要预缓存的网址列表，并将该预缓存清单添加到现有服务工作器文件中。否则，系统会将文件保持原样。

何时使用 InjectManifest

• 您希望更好地控制 Service Worker。
• 您想预缓存文件。
• 您需要自定义路由和策略。
• 您希望将服务工件与其他平台功能（例如网站推送）搭配使用。

不应使用 InjectManifest 的情况

• 您希望以最简单的方式向网站添加 Service Worker。

GenerateSW 插件

您可以将 GenerateSW 插件添加到 webpack 配置，如下所示：

// Inside of webpack.config.js:
const {GenerateSW} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new GenerateSW({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      navigateFallback: '...',
      runtimeCaching: [{
        // Routing via a matchCallback function:
        urlPattern: ({request, url}) => ...,
        handler: '...',
        options: {
          cacheName: '...',
          expiration: {
            maxEntries: ...,
          },
        },
      }, {
        // Routing via a RegExp:
        urlPattern: new RegExp('...'),
        handler: '...',
        options: {
          cacheName: '...',
          plugins: [..., ...],
        },
      }],
      skipWaiting: ...,
    }),
  ],
};

这将生成一个服务工作器，其中包含为配置中提取的所有 webpack 资源以及提供的运行时缓存规则设置的预缓存。

您可以在参考文档中找到一整套配置选项。

InjectManifest 插件

您可以将 InjectManifest 插件添加到 webpack 配置，如下所示：

// Inside of webpack.config.js:
const {InjectManifest} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new InjectManifest({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      swSrc: '...',
    }),
  ],
};

这将根据配置中提取的 webpack 资源创建预缓存清单，并将其注入捆绑和编译后的 Service Worker 文件中。

您可以在参考文档中找到一整套配置选项。

附加信息

有关在更大的 webpack 构建环境中使用插件的指南，请参阅 webpack 文档的渐进式 Web 应用部分。

类型

GenerateSW

此类支持在 webpack 编译过程中创建新的可供使用的服务工文件。

在 webpack 配置的 plugins 数组中使用 GenerateSW 的实例。

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new GenerateSW({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  navigateFallback: '...',
  runtimeCaching: [{
    // Routing via a matchCallback function:
    urlPattern: ({request, url}) => ...,
    handler: '...',
    options: {
      cacheName: '...',
      expiration: {
        maxEntries: ...,
      },
    },
  }, {
    // Routing via a RegExp:
    urlPattern: new RegExp('...'),
    handler: '...',
    options: {
      cacheName: '...',
      plugins: [..., ...],
    },
  }],
  skipWaiting: ...,
});

属性

• 构造函数

  void

  创建一个 GenerateSW 实例。

  constructor 函数如下所示：

  (config?: GenerateSWConfig) => {...}

  • config

    GenerateSWConfig（可选）

  • 返回

    GenerateSW

• config

  GenerateSWConfig

GenerateSWConfig

属性

• additionalManifestEntries

  (string | ManifestEntry)[] 可选

  要预缓存的条目列表，以及在 build 配置过程中生成的所有条目。

• babelPresetEnvTargets

  string[] 选填

  默认值为：["chrome >= 56"]

  转译服务工件软件包时要传递给 babel-preset-env 的目标。

• cacheId

  字符串（选填）

  要附加到缓存名称前面的可选 ID。这对于本地开发非常有用，因为在本地开发中，多个网站可能会从同一 http://localhost:port 源提供服务。

• 分块

  string[] 可选

  一个或多个区块名称，其对应的输出文件应包含在预缓存清单中。

• cleanupOutdatedCaches

  布尔值（可选）

  默认值为 false

  Workbox 是否应尝试识别和删除由不兼容的较低版本创建的任何预缓存。

• clientsClaim

  布尔值（可选）

  默认值为 false

  Service Worker 是否应在激活后立即开始控制任何现有客户端。

• directoryIndex

  字符串（选填）

  如果针对以 / 结尾的网址的导航请求与预缓存网址不匹配，系统会将此值附加到网址，并检查是否与预缓存网址匹配。此值应设置为您的 Web 服务器用于目录索引的值。

• disableDevLogs

  布尔值（可选）

  默认值为：false

• dontCacheBustURLsMatching

  正则表达式（可选）

  系统会假定与此匹配的资源通过其网址具有唯一的版本号，并且会免于在填充预缓存时执行的常规 HTTP 破坏缓存操作。虽然不是强制要求，但如果您的现有构建流程已将 [hash] 值插入每个文件名中，建议您提供用于检测该值的正则表达式，因为这将减少预缓存时消耗的带宽。

• 排除

  (string | RegExp | function)[] 可选

  一个或多个用于从预缓存清单中排除资源的说明符。 系统会按照与 webpack 的标准 exclude 选项相同的规则对其进行解读。如果未提供，则默认值为 [/\.map$/, /^manifest.*\.js$]。

• excludeChunks

  string[] 可选

  一个或多个分块名称，其对应的输出文件应从预缓存清单中排除。

• ignoreURLParametersMatching

  RegExp[] 可选

  在查找预缓存匹配项之前，系统会移除与此数组中的某个正则表达式匹配的所有搜索参数名称。如果用户可能会请求包含网址参数（例如用于跟踪流量来源）的网址，此功能会很有用。如果未提供，则默认值为 [/^utm_/, /^fbclid$/]。

• importScripts

  string[] 可选

  应传递给生成的服务工作文件内的 importScripts() 的 JavaScript 文件列表。如果您想让 Workbox 创建顶级服务工作器文件，但又想添加一些额外的代码（例如推送事件监听器），这非常有用。

• importScriptsViaChunks

  string[] 可选

  一个或多个 webpack 分块的名称。这些分块的内容将通过调用 importScripts() 包含在生成的 Service Worker 中。

• 包含

  (string | RegExp | function)[] 选填

  用于在预缓存清单中添加资源的一个或多个说明符。 系统会按照与 webpack 的标准 include 选项相同的规则对其进行解读。

• inlineWorkboxRuntime

  布尔值（可选）

  默认值为：false

  Workbox 库的运行时代码应包含在顶级服务工件中，还是拆分为需要与服务工件一起部署的单独文件。将运行时分开意味着，每次顶级 Service Worker 发生更改时，用户都无需重新下载 Workbox 代码。

• manifestEntries

  ManifestEntry[] 可选

• manifestTransforms

  ManifestTransform[] 可选

  一个或多个将依次应用于生成的清单的函数。如果还指定了 modifyURLPrefix 或 dontCacheBustURLsMatching，系统会先应用其对应的转换。

• maximumFileSizeToCacheInBytes

  number 可选

  默认值为：2097152

  此值可用于确定将预缓存的文件大小上限。这样可以防止您在无意间预缓存可能意外地与您的某种模式匹配的超大文件。

• 模式

  字符串（选填）

  如果设置为“production”，则系统会生成一个排除了调试信息的经过优化的服务工件软件包。如果未在此处明确配置，系统将使用在当前 webpack 编译中配置的 mode 值。

• modifyURLPrefix

  对象（可选）

  用于将字符串前缀映射到替换字符串值的对象。例如，如果您的网站托管设置与本地文件系统设置不匹配，您可以使用此方法从清单条目中移除或添加路径前缀。作为更灵活的替代方案，您可以使用 manifestTransforms 选项，并提供一个函数，该函数使用您提供的任何逻辑修改清单中的条目。

  用法示例：

  // Replace a '/dist/' prefix with '/', and also prepend
  // '/static' to every URL.
  modifyURLPrefix: {
    '/dist/': '/',
    '': '/static',
  }
  

• navigateFallback

  字符串（选填）

  默认值为：null

  如果已指定，则针对未预缓存的网址的所有导航请求都将通过提供的网址中的 HTML 来实现。您必须传入预缓存清单中列出的 HTML 文档的网址。这适用于单页应用场景，在这种场景中，您希望所有导航都使用通用的应用壳 HTML。

• navigateFallbackAllowlist

  RegExp[] 可选

  可选的正则表达式数组，用于限制配置的 navigateFallback 行为适用于哪些网址。如果您只想将网站的部分网址视为单页应用的一部分，此方法非常有用。如果同时配置了 navigateFallbackDenylist 和 navigateFallbackAllowlist，则拒绝列表优先。

  注意：在导航期间，系统可能会针对每个目标网址对这些正则表达式进行评估。避免使用复杂的正则表达式，否则用户在浏览您的网站时可能会出现延迟。

• navigateFallbackDenylist

  RegExp[] 可选

  可选的正则表达式数组，用于限制配置的 navigateFallback 行为适用于哪些网址。如果您只应将网站的部分网址视为单页应用的一部分，此功能非常有用。如果同时配置了 navigateFallbackDenylist 和 navigateFallbackAllowlist，则拒绝列表优先。

  注意：在导航期间，系统可能会针对每个目标网址对这些正则表达式进行评估。避免使用复杂的正则表达式，否则用户在浏览您的网站时可能会出现延迟。

• navigationPreload

  布尔值（可选）

  默认值为：false

  是否在生成的 Service Worker 中启用导航预加载。将其设置为 true 后，您还必须使用 runtimeCaching 设置与导航请求匹配的适当响应策略，并使用预加载的响应。

• offlineGoogleAnalytics

  boolean | GoogleAnalyticsInitializeOptions 可选

  默认值为：false

  控制是否支持离线 Google Analytics 。如果为 true，系统会将对 workbox-google-analytics 的 initialize() 的调用添加到生成的 Service Worker 中。如果设置为 Object，系统会将该对象传入 initialize() 调用，以便您自定义行为。

• runtimeCaching

  RuntimeCaching[] 可选

  使用 Workbox 的构建工具生成服务工件时，您可以指定一个或多个运行时缓存配置。然后，系统会使用您定义的匹配和处理程序配置将这些调用转换为 workbox-routing.registerRoute 调用。

  如需了解所有选项，请参阅 workbox-build.RuntimeCaching 文档。以下示例展示了一个典型配置，定义了两个运行时路由：

• skipWaiting

  布尔值（可选）

  默认值为：false

  是否向生成的 Service Worker 添加对 skipWaiting() 的无条件调用。如果为 false，则将改为添加 message 监听器，从而允许客户端页面通过对等待的 Service Worker 调用 postMessage({type: 'SKIP_WAITING'}) 来触发 skipWaiting()。

• 源映射

  布尔值（可选）

  默认值为：true

  是否为生成的 Service Worker 文件创建源映射。

• swDest

  字符串（选填）

  默认值为 "service-worker.js"

  此插件创建的 Service Worker 文件的资源名称。

InjectManifest

此类支持编译通过 swSrc 提供的 Service Worker 文件，并根据 webpack 资源流水线向该 Service Worker 注入网址和修订信息列表以进行预缓存。

在 webpack 配置的 plugins 数组中使用 InjectManifest 的实例。

除了注入清单之外，此插件还会使用主 webpack 配置中的选项编译 swSrc 文件。

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new InjectManifest({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  swSrc: '...',
});

属性

• 构造函数

  void

  创建 InjectManifest 的实例。

  constructor 函数如下所示：

  (config: WebpackInjectManifestOptions) => {...}

  • config

    WebpackInjectManifestOptions

  • 返回

    InjectManifest

• config

  WebpackInjectManifestOptions

属性

default

类型

对象

属性

• GenerateSW

  查询

• InjectManifest

  查询