工作区 build

workbox-build 模块可集成到基于节点的构建流程中，并且可以生成整个 Service Worker，也可以仅生成可预缓存且可在现有 Service Worker 中使用的资源列表。

大多数开发者会使用的两种模式是 generateSW 和 injectManifest。以下问题的答案可帮助您选择合适的模式和配置。

使用哪种模式

generateSW

generateSW 模式可为您创建 Service Worker 文件（通过配置选项进行自定义），并将其写入磁盘。

何时使用 generateSW

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

何时不应使用 generateSW

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

injectManifest

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

何时使用 injectManifest

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

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

这将生成一个 Service Worker，该 Service Worker 为您的配置选取的所有文件设置了预缓存设置，并且提供了运行时缓存规则。

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

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 模式在概念上类似，但前者不是将清单添加到源 Service Worker 文件中，而是返回一组清单条目以及有关条目数量和总大小的信息。

您可以使用最常见的配置选项在基于节点的构建脚本中使用 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

    (字符串 | ManifestEntry)[] 可选

    要预缓存的条目列表，以及作为 build 配置的一部分生成的任何条目。

  • dontCacheBustURLsMatching

    正则表达式（可选）

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

  • manifestTransforms

    ManifestTransform[] 可选

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

  • maximumFileSizeToCacheInBytes

    数字可选

    默认值为：2097152

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

  • modifyURLPrefix

    对象（可选）

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

    用法示例：

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

BuildResult

类型

省略 <GetManifestResult"manifestEntries"
> 和对象

属性

  • filePaths

    字符串[]

GeneratePartial

属性

  • babelPresetEnvTargets

    string[] 可选

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

    转译 Service Worker 软件包时要传递给 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[] 可选

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

  • inlineWorkboxRuntime

    布尔值 选填

    默认值为 false

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

  • 模式

    字符串（可选）

    默认值为："production"

    如果设置为“生产”，则将生成不包括调试信息的优化 Service Worker 软件包。如果未在此处明确配置，系统将使用 process.env.NODE_ENV 值；否则，将回退到 'production'。

  • 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 文件创建源映射。

GenerateSWOptions

类型

BasePartial 和 GlobPartial & GeneratePartial & RequiredSWDestPartial 和 OptionalGlobDirectoryPartial

GetManifestOptions

类型

BasePartial 和 GlobPartial 和 RequiredGlobDirectoryPartial

GetManifestResult

属性

  • 计数

    number

  • manifestEntries

    ManifestEntry[]

  • 大小

    number

  • 警告

    字符串[]

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

    string

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

ManifestEntry

属性

  • 完整性

    字符串（可选）

  • 修订版本

    string

  • 网址

    string

ManifestTransform()

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

类型

功能

参数

  • manifestEntries

    （ManifestEntry 和对象）[]

    • 大小

      number

  • 汇编

    未知（可选）

返回

ManifestTransformResult

属性

  • 清单

    （ManifestEntry 和对象）[]

    • 大小

      number

  • 警告

    string[] 可选

OptionalGlobDirectoryPartial

属性

  • globDirectory

    字符串（可选）

    要与 globPatterns 匹配的本地目录。该路径相对于当前目录。

RequiredGlobDirectoryPartial

属性

  • globDirectory

    string

    要与 globPatterns 匹配的本地目录。该路径相对于当前目录。

RequiredSWDestPartial

属性

  • swDest

    string

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

RuntimeCaching

属性

StrategyName

枚举

"CacheFirst"

"CacheOnly"

WebpackGenerateSWOptions

类型

BasePartial 和 WebpackPartial & GeneratePartial & WebpackGenerateSWPartial

WebpackGenerateSWPartial

属性

  • importScriptsViaChunks

    string[] 可选

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

  • swDest

    字符串（可选）

    默认值为 "service-worker.js"

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

WebpackInjectManifestOptions

类型

BasePartial 和 WebpackPartial 和 InjectPartial 和 WebpackInjectManifestPartial

WebpackInjectManifestPartial

属性

  • compileSrc

    布尔值 选填

    默认值为 true

    如果设置为 true（默认值），则 swSrc 文件将由 webpack 编译。如果设为 false，将不会进行编译（无法使用 webpackCompilationPlugins）。如果要将清单注入（例如，JSON 文件）中，请设置为 false。

  • swDest

    字符串（可选）

    将由此插件创建的 Service Worker 文件的资源名称。如果省略，名称将基于 swSrc 名称。

  • webpackCompilationPlugins

    any[] 可选属性

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

WebpackPartial

属性

  • 数据块

    string[] 可选

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

  • 排除

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

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

  • excludeChunks

    string[] 可选

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

  • 包括

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

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

  • 模式

    字符串（可选）

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

方法

copyWorkboxLibraries()

workbox-build.copyWorkboxLibraries(
  destDirectory: string,
)

这会将 Workbox 使用的一组运行时库复制到一个本地目录，该目录应与 Service Worker 文件一起部署。

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

提供此方法是为了方便使用 workbox-build.injectManifest 的开发者不愿使用 Workbox 的 CDN 副本。使用 workbox-build.generateSW 的开发者无需明确调用此方法。

参数

  • destDirectory

    string

    指向父目录的路径，系统将在该父目录下创建新的库目录。

返回

  • 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

    string

  • buildType

    BuildType

返回

  • string

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: '...',
});

参数

返回