工作区 build

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

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

使用哪种模式

generateSW

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

何时使用 generateSW

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

不适用 generateSW 的情形

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

injectManifest

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

何时使用 injectManifest

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

不适用 injectManifest 的情形

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

generateSW 模式

您可以在基于节点的 build 脚本中使用 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 模式

您可以在基于节点的 build 脚本中使用 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 模式类似，但它不是将清单添加到源服务工作线程文件中，而是返回清单条目数组以及有关条目数和总大小的信息。

您可以在基于节点的 build 脚本中使用 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

类型

Omit<GetManifestResult"manifestEntries"
> & object

属性

  • filePaths

    字符串[]

GeneratePartial

属性

  • babelPresetEnvTargets

    string[] 可选

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

    在转译 service worker 软件包时要传递给 babel-preset-env 的目标。

  • cacheId

    字符串 可选

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

  • cleanupOutdatedCaches

    布尔值 （可选）

    默认值为：false

    Workbox 是否应尝试识别并删除旧的不兼容版本创建的所有预缓存。

  • clientsClaim

    布尔值 （可选）

    默认值为：false

    服务工作线程是否应在激活后立即开始控制任何现有客户端。

  • directoryIndex

    字符串 可选

    如果以 / 结尾的网址的导航请求无法与预缓存的网址匹配，系统会将此值附加到该网址，然后检查是否存在预缓存匹配项。此值应设置为 Web 服务器用于其目录索引的值。

  • disableDevLogs

    布尔值 （可选）

    默认值为：false

  • ignoreURLParametersMatching

    RegExp[] 可选

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

  • importScripts

    string[] 可选

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

  • inlineWorkboxRuntime

    布尔值 （可选）

    默认值为：false

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

  • 模式

    字符串 可选

    默认值为：“production”

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

  • navigateFallback

    字符串 可选

    默认值为：null

    如果指定了该属性，则对于未预缓存的网址，所有导航请求都将通过所提供的网址中的 HTML 来满足。您必须传入预缓存清单中列出的 HTML 文档的网址。此方法旨在用于单页应用场景，在此场景中，您希望所有导航都使用通用的 App Shell HTML。

  • navigateFallbackAllowlist

    RegExp[] 可选

    一个可选的正则表达式数组，用于限制配置的 navigateFallback 行为所适用的网址。如果只有一部分网站网址应被视为属于 SPA，此功能会非常有用。如果同时配置了 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 的 build 工具生成 service worker 时，您可以指定一个或多个运行时缓存配置。然后，系统会使用您定义的匹配和处理程序配置将这些调用转换为 workbox-routing.registerRoute 调用。

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

  • skipWaiting

    布尔值 （可选）

    默认值为：false

    是否向生成的 Service Worker 添加对 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 基础知识。

  • templatedURLs

    对象（可选）

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

InjectManifestOptions

类型

BasePartial & GlobPartial & InjectPartial & RequiredSWDestPartial & RequiredGlobDirectoryPartial

InjectPartial

属性

  • injectionPoint

    字符串 可选

    默认值为："self.__WB_MANIFEST"

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

  • swSrc

    字符串

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

ManifestEntry

属性

  • 完整性

    字符串 可选

  • 修订版本

    字符串

  • 网址

    字符串

ManifestTransform()

workbox-build.ManifestTransform(
  manifestEntries: (ManifestEntry & object)[],
  compilation?: unknown,
): Promise<ManifestTransformResult> | ManifestTransformResult

类型

函数

参数

  • 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 chunk 的名称。这些块的内容将通过对 importScripts() 的调用包含在生成的 Service Worker 中。

  • swDest

    字符串 可选

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

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

WebpackInjectManifestOptions

类型

BasePartial & WebpackPartial & InjectPartial & WebpackInjectManifestPartial

WebpackInjectManifestPartial

属性

  • compileSrc

    布尔值 （可选）

    默认值为：true

    如果值为 true（默认值），webpack 将编译 swSrc 文件。如果值为 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,
): Promise<string>

此命令会将 Workbox 使用的一组运行时库复制到本地目录中，该目录应与您的 service worker 文件一起部署。

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

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

参数

  • destDirectory

    字符串

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

返回

  • Promise<string>

    新创建的目录的名称。

generateSW()

workbox-build.generateSW(
  config: GenerateSWOptions,
): Promise<BuildResult>

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

它还接受用于配置 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,
): Promise<GetManifestResult>

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

// 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,
): string

参数

  • moduleName

    字符串

  • buildType

    BuildType

返回

  • 字符串

injectManifest()

workbox-build.injectManifest(
  config: InjectManifestOptions,
): Promise<BuildResult>

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

清单会注入到 swSrc 文件中，而占位字符串 injectionPoint 会确定清单应位于文件中的哪个位置。

注入清单的最终服务工作线程文件会写入磁盘上的 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: '...', });

参数

返回