Workbox-webpack-plugin

Workbox 提供了两个 Webpack 插件：一个可为你生成完整的 Service Worker，另一个用于生成要预缓存的资产列表（已注入到 Service Worker 文件）。

这两个插件作为 workbox-webpack-plugin 模块中的两个类实现，分别名为 GenerateSW 和 InjectManifest。以下问题的答案可帮助您选择合适的插件和配置。

要使用哪个插件

GenerateSW

GenerateSW 插件将为您创建 Service Worker 文件，并将其添加到 webpack 资源流水线。

何时使用 GenerateSW

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

何时不应使用 GenerateSW

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

InjectManifest

InjectManifest 插件将生成要预缓存的网址列表，并将该预缓存清单添加到现有 Service Worker 文件中。否则，该文件将保持原样。

何时使用 InjectManifest

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

何时不应使用 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: ...,
    }),
  ],
};

这将生成一个 Service Worker，该 Service Worker 为您的配置选取的所有 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 编译过程中创建可直接使用的新 Service Worker 文件。

在 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"]

  转译 Service Worker 软件包时要传递给 babel-preset-env 的目标。

• cacheId

  字符串（可选）

  附加到缓存名称前面的可选 ID。这主要适用于本地开发，其中可能会从同一 http://localhost:port 来源提供多个网站。

• 数据块

  string[] 可选

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

• cleanupOutdatedCaches

  布尔值 选填

  默认值为 false

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

• clientsClaim

  布尔值 选填

  默认值为 false

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

• directoryIndex

  字符串（可选）

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

• disableDevLogs

  布尔值 选填

  默认值为 false

• dontCacheBustURLsMatching

  正则表达式（可选）

  系统会假定与此类资源匹配的资源通过其网址进行唯一版本控制，并免受在填充预缓存时执行的常规 HTTP 缓存无效化操作。如果您的现有构建流程已在每个文件名中插入 [hash] 值，建议您提供一个可以检测这一点的正则表达式，因为这可以减少预缓存时的带宽消耗，不过并非强制性要求。

• 排除

  (字符串 | 正则表达式 | 函数)[] 可选

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

• excludeChunks

  string[] 可选

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

• ignoreURLParametersMatching

  RegExp[] 可选

  在查找预缓存匹配项之前，系统会移除与此数组中的某个正则表达式匹配的所有搜索参数名称。如果您的用户请求的网址包含一些用于跟踪流量来源的网址参数，那么这种做法非常有用。如果未提供，则默认值为 [/^utm_/, /^fbclid$/]。

• importScripts

  string[] 可选

  应传递到生成的 Service Worker 文件内的 importScripts() 的 JavaScript 文件列表。如果您希望让 Workbox 创建顶级 Service Worker 文件，但想要添加一些额外的代码（如推送事件监听器），此方法会非常有用。

• importScriptsViaChunks

  string[] 可选

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

• 包括

  (字符串 | 正则表达式 | 函数)[] 可选

  用于在预缓存清单中包含资源的一个或多个说明符。这解读遵循与 webpack 的标准 include 选项相同的规则。

• inlineWorkboxRuntime

  布尔值 选填

  默认值为 false

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

• manifestEntries

  ManifestEntry[] 可选

• manifestTransforms

  ManifestTransform[] 可选

  将针对生成的清单依序应用的一个或多个函数。如果还指定了 modifyURLPrefix 或 dontCacheBustURLsMatching，则首先应用其相应的转换。

• maximumFileSizeToCacheInBytes

  数字可选

  默认值为：2097152

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

• 模式

  字符串（可选）

  如果设置为“生产”，则将生成不包括调试信息的优化 Service Worker 软件包。如果未在此处明确配置，将使用当前 webpack 编译中配置的 mode 值。

• modifyURLPrefix

  对象（可选）

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

  用法示例：

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

• navigateFallback

  字符串（可选）

  默认值为 null

  如果指定此参数，针对未预缓存的网址的所有导航请求都将通过所提供的网址中的 HTML 执行。您必须传入预缓存清单中列出的 HTML 文档的网址。这适用于单页应用场景，在此场景中，您希望所有导航都使用通用的 App Shell HTML。

• navigateFallbackAllowlist

  RegExp[] 可选

  可选的正则表达式数组，用于限制所配置的 navigateFallback 行为适用的网址。如果只有您网站的部分网址应被视为单页应用的一部分，这种做法非常有用。如果同时配置了 navigateFallbackDenylist 和 navigateFallbackAllowlist，则拒绝名单优先。

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

• navigateFallbackDenylist

  RegExp[] 可选

  可选的正则表达式数组，用于限制所配置的 navigateFallback 行为适用的网址。如果只有您网站的部分网址应被视为单页应用的一部分，这种做法非常有用。如果同时配置了 navigateFallbackDenylist 和 navigateFallbackAllowlist，则拒绝名单优先。

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

• navigationPreload

  布尔值 选填

  默认值为 false

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

• offlineGoogleAnalytics

  布尔值 | GoogleAnalyticsInitializeOptions 可选

  默认值为 false

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

• runtimeCaching

  RuntimeCaching[] 可选

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

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

• skipWaiting

  布尔值 选填

  默认值为 false

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

• 源代码映射

  布尔值 选填

  默认值为 true

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

• swDest

  字符串（可选）

  默认值为 "service-worker.js"

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

InjectManifest

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

在 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

  个查询