工作区 build

workbox-build 模块会集成到基于节点的构建流程中，可以生成整个服务工件，也可以仅生成要预缓存的资源列表，以便在现有服务工件中使用。

大多数开发者将使用 generateSW 和 injectManifest 这两种模式。回答以下问题有助于您选择合适的模式和配置。

使用哪种模式

generateSW

generateSW 模式会为您创建一个服务工件文件（通过配置选项进行自定义），并将其写入磁盘。

何时使用 generateSW

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

不应使用 generateSW 的情况

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

injectManifest

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

何时使用 injectManifest

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

不应使用 injectManifest 的情况

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

generateSW 模式

您可以在基于节点的构建脚本中使用 generateSW 模式，并使用最常见的配置选项，如下所示：

// Inside of build.js:
const {generateSW} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
generateSW({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  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: ...,
  swDest: '...',
}).then(({count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while generating a service worker:',
      warnings.join('\n')
    );
  }

  console.log(`Generated a service worker, which will precache ${count} files, totaling ${size} bytes.`);
});

这将生成一个服务工作线程，其中包含针对配置中提取的所有文件以及提供的运行时缓存规则的预缓存设置。

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

injectManifest 模式

您可以在基于节点的构建脚本中使用 injectManifest 模式，并使用最常见的配置选项，如下所示：

// Inside of build.js:
const {injectManifest} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
injectManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
  swDest: '...',
  swSrc: '...',
}).then(({count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while injecting the manifest:',
      warnings.join('\n')
    );
  }

  console.log(`Injected a manifest which will precache ${count} files, totaling ${size} bytes.`);
});

这将根据配置中提取的文件创建预缓存清单，并将其注入现有的 Service Worker 文件中。

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

其他模式

我们预计 generateSW 或 injectManifest 将满足大多数开发者的需求。不过，workbox-build 支持的另一种模式可能适用于某些用例。

getManifest 模式

这在概念上与 injectManifest 模式类似，但它不是将清单添加到源服务工文件中，而是返回清单条目数组以及条目数量和总大小的相关信息。

您可以在基于节点的构建脚本中使用 injectManifest 模式，并使用最常见的配置选项，如下所示：

// Inside of build.js:
const {getManifest} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
getManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
}).then(({manifestEntries, count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while getting the manifest:',
      warnings.join('\n')
    );
  }

  // Do something with the manifestEntries, and potentially log count and size.
});

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

类型

BasePartial

属性

  • additionalManifestEntries

    (string | ManifestEntry)[] 可选

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

  • dontCacheBustURLsMatching

    正则表达式（可选）

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

  • manifestTransforms

    ManifestTransform[] 可选

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

  • maximumFileSizeToCacheInBytes

    number 可选

    默认值为：2097152

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

  • modifyURLPrefix

    对象（可选）

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

    用法示例：

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

BuildResult

类型

忽略<GetManifestResult"manifestEntries"
> & object

属性

  • filePaths

    字符串[]

GeneratePartial

属性

  • babelPresetEnvTargets

    string[] 可选

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

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

  • cacheId

    字符串（选填）

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

  • cleanupOutdatedCaches

    布尔值（可选）

    默认值为：false

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

  • clientsClaim

    布尔值（可选）

    默认值为：false

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

  • directoryIndex

    字符串（选填）

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

  • disableDevLogs

    布尔值（可选）

    默认值为：false

  • ignoreURLParametersMatching

    RegExp[] 可选

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

  • importScripts

    string[] 可选

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

  • inlineWorkboxRuntime

    布尔值（可选）

    默认值为：false

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

  • 模式

    字符串（选填）

    默认值为：“production”

    如果设置为“production”，则系统会生成一个排除了调试信息的经过优化的服务工件软件包。如果未在此处明确配置，则系统会使用 process.env.NODE_ENV 值，如果未能使用该值，则会回退到 'production'。

  • 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

    是否向生成的服务工作器添加对 skipWaiting() 的无条件调用。如果为 false，则系统会改为添加 message 监听器，以允许客户端页面通过对等待中的服务工作器调用 postMessage({type: 'SKIP_WAITING'}) 来触发 skipWaiting()。

  • sourcemap

    布尔值（可选）

    默认值为：true

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

GenerateSWOptions

类型

BasePartial & GlobPartial & GeneratePartial & RequiredSWDestPartial & OptionalGlobDirectoryPartial

GetManifestOptions

类型

BasePartial & GlobPartial & RequiredGlobDirectoryPartial

GetManifestResult

属性

  • 计数

    数值

  • manifestEntries

    ManifestEntry[]

  • size

    数值

  • 警告

    字符串[]

GlobPartial

属性

  • globFollow

    布尔值（可选）

    默认值为：true

    确定在生成预缓存清单时是否要遵循符号链接。如需了解详情，请参阅 glob 文档中的 follow 定义。

  • globIgnores

    string[] 可选

    默认值为：["**\/node_modules\/**\/*"]

    一组与文件匹配的模式，用于在生成预缓存清单时始终排除这些文件。如需了解详情，请参阅 glob 文档中的 ignore 定义。

  • globPatterns

    string[] 可选

    默认值为：["**\/*.{js,wasm,css,html}"]

    与以下任一模式匹配的文件都将包含在预缓存清单中。如需了解详情，请参阅 glob 入门。

  • globStrict

    布尔值（可选）

    默认值为：true

    如果为 true，则在生成预缓存清单时读取目录时出错会导致构建失败。如果为 false，系统会跳过存在问题的目录。如需了解详情，请参阅 glob 文档中的 strict 定义。

  • templatedURLs

    对象（可选）

    如果网址是根据某种服务器端逻辑呈现的，其内容可能取决于多个文件或某个其他唯一字符串值。此对象中的键是服务器呈现的网址。如果值是字符串数组，则会被解读为 glob 模式，并且与模式匹配的任何文件的内容都将用于为网址创建唯一的版本。如果与单个字符串搭配使用，则会被解读为您为给定网址生成的唯一版本信息。

InjectManifestOptions

类型

BasePartial & GlobPartial & InjectPartial & RequiredSWDestPartial & RequiredGlobDirectoryPartial

InjectPartial

属性

  • injectionPoint

    字符串（选填）

    默认值为："self.__WB_MANIFEST"

    要在 swSrc 文件中查找的字符串。找到后，系统会将其替换为生成的预缓存清单。

  • swSrc

    字符串

    将在构建过程中读取的服务工件文件的路径和文件名（相对于当前工作目录）。

ManifestEntry

属性

  • 完整性

    字符串（选填）

  • 修订版本

    字符串

  • 网址

    字符串

ManifestTransform()

workbox-build.ManifestTransform(
  manifestEntries: (ManifestEntry & object)[],
  compilation?: unknown,
)

类型

函数

参数

  • manifestEntries

    (ManifestEntry & object)[]

    • size

      数值

  • 编译

    未知（可选）

返回

ManifestTransformResult

属性

  • 清单

    (ManifestEntry & object)[]

    • size

      数值

  • 警告

    string[] 可选

OptionalGlobDirectoryPartial

属性

  • globDirectory

    字符串（选填）

    您希望与 globPatterns 匹配的本地目录。路径相对于当前目录。

RequiredGlobDirectoryPartial

属性

  • globDirectory

    字符串

    您希望与 globPatterns 匹配的本地目录。路径相对于当前目录。

RequiredSWDestPartial

属性

  • swDest

    字符串

    构建流程将创建的服务工件文件的路径和文件名（相对于当前工作目录）。它必须以“.js”结尾。

RuntimeCaching

属性

StrategyName

枚举

"CacheFirst"

"CacheOnly"

"NetworkFirst"

"NetworkOnly"

"StaleWhileRevalidate"

WebpackGenerateSWOptions

类型

BasePartial & WebpackPartial & GeneratePartial & WebpackGenerateSWPartial

WebpackGenerateSWPartial

属性

  • importScriptsViaChunks

    string[] 可选

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

  • swDest

    字符串（选填）

    默认值为：“service-worker.js”

    此插件创建的服务工作器文件的资源名称。

WebpackInjectManifestOptions

类型

BasePartial & WebpackPartial & InjectPartial & WebpackInjectManifestPartial

WebpackInjectManifestPartial

属性

  • compileSrc

    布尔值（可选）

    默认值为：true

    如果为 true（默认值），则 swSrc 文件将由 webpack 编译。当 false 时，系统不会进行编译（并且无法使用 webpackCompilationPlugins）。如果您想将清单注入到 JSON 文件等位置，请将其设为 false。

  • swDest

    字符串（选填）

    此插件将创建的服务工件文件的资源名称。如果省略，系统将根据 swSrc 名称生成名称。

  • webpackCompilationPlugins

    any[] 可选

    在编译 swSrc 输入文件时将使用的可选 webpack 插件。仅当 compileSrc 为 true 时有效。

WebpackPartial

属性

  • 分块

    string[] 可选

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

  • 排除

    (string | RegExp | function)[] 可选

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

  • excludeChunks

    string[] 可选

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

  • 包含

    (string | RegExp | function)[] 可选

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

  • 模式

    字符串（选填）

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

方法

copyWorkboxLibraries()

workbox-build.copyWorkboxLibraries(
  destDirectory: string,
)

这会将 Workbox 使用的一组运行时库复制到一个本地目录，该目录应与您的服务工作器文件一起部署。

除了部署这些本地副本之外，您还可以改为使用 Workbox 的官方 CDN 网址。

此方法面向使用 workbox-build.injectManifest 且不想使用 Workbox CDN 副本的开发者提供。使用 workbox-build.generateSW 的开发者无需显式调用此方法。

参数

  • destDirectory

    字符串

    要创建库的新目录的父目录的路径。

返回

  • Promise<string>

    新创建的目录的名称。

generateSW()

workbox-build.generateSW(
  config: GenerateSWOptions,
)

此方法会根据您提供的选项创建要预缓存的网址列表（称为“预缓存清单”）。

它还会接受用于配置 Service Worker 行为的其他选项，例如它应使用的任何 runtimeCaching 规则。

它会根据预缓存清单和其他配置，将可供使用的 Service Worker 文件写入 swDest 磁盘。

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, size, warnings} = await generateSW({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  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: ...,
  swDest: '...',
});

参数

返回

getManifest()

workbox-build.getManifest(
  config: GetManifestOptions,
)

此方法会根据您提供的选项，返回要预缓存的网址列表（称为“预缓存清单”），以及条目数量和大小的详细信息。

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, manifestEntries, size, warnings} = await getManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
});

参数

返回

getModuleURL()

workbox-build.getModuleURL(
  moduleName: string,
  buildType: BuildType,
)

参数

  • moduleName

    字符串

  • buildType

    BuildType

返回

  • 字符串

injectManifest()

workbox-build.injectManifest(
  config: InjectManifestOptions,
)

此方法会根据您提供的选项创建要预缓存的网址列表（称为“预缓存清单”）。

清单会注入 swSrc 文件中，占位符字符串 injectionPoint 决定清单应位于文件中的什么位置。

最终的 service worker 文件（已注入清单）会写入 swDest 磁盘。

此方法不会编译或打包您的 swSrc 文件；它只会处理注入清单。

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, size, warnings} = await injectManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
  swDest: '...',
  swSrc: '...',
});

参数

返回