Workbox CLI中文版

在写PWA应用时，用到WorkBox工具，使用过程中发现没有中文的帮助文档，为了体验好一些，也为了方便自己和他人查看，在这里翻译了一下 workbox-cli 。

Workbox CLI 是什么?

Workbox命令行（在 workbox-cli 包内）由 workbox 的NodeJS程序构成，可以运行在Windows、Mac和类UNIX环境下。 workbox-cli 包含了 workbox-build 模块，并提供了一个通过领过配置，将Workbox集成到命令行构建过程的简单方法。

安装 CLI

安装这个CLI很简单，只需要在终端中运行以下命令。

NPM:

$ npm install workbox-cli --global
复制代码

YARN:

$ yarn global add workbox-cli
复制代码

CLI模式

CLI有4个不同的模式：

• wizard : 通过步骤向导为你的项目安装Workbox。
• generateSW : 生成一个完整的service worker。
• injectManifest : 将资源注入到你的项目 precache 中。
• copyLibraries : 复制Workbox库到指定目录。

wizard

Workbox的 wizard 会询问你本地的安装目录和你想哪些文件预缓存的一系列问题。你的回答会生成一个配置文件，用于 generateSW 模式时使用。

大多数开发者只会运行一次 workbox wizard ，你可以使用任何构建配置支持的选项去手动修改初始化生成的配置文件。

使用 wizard ：

$ workbox wizard
复制代码

generateSW

你可以使用Workbox CLI通过配置文件去生成完正的service woker（像通过 wizard 生成文件一样）。

只需要运行下面命令：

$ workbox generateSW path/to/config.js
复制代码

Workbox内置的预缓存和运行时缓存功能，不需要再去手动定制他们的service worker的行为，推荐使用 generateSW 模式。

:white_check_mark:什么时候使用 generateSW

• 你想预缓存文件。
• 你需要一些简单的运行时配置（例如，配置允许你定义的路由和策略）。

:x:什么时候不使用 generateSW

• 你想使用一些其他的Service Worker特性。
• 你想导入其他脚本或者添加其他逻辑。

injectManifest

对于想要更多控制最终生成的service worker文件的开发者可以使用 injectManifest 模式。这个模式需要你有一个存在的service worker文件（文件位置在 config.js 中指定）。

运行 workbox injectManifest 时，它会在你的源service worker文件中找指定的字符串（默认 precaching.precacheAndRoute([] ）。它将空数组替换为precache的URL列表，并将service worker写到 config.js 配置项中指定的目标位置。在源service worker文件中的其他代码保持不变。

可以这样使用：

$ workbox injectManifest path/to/config.js
复制代码

:white_check_mark:什么时候使用 injectManifest

• 你想更好的控制service worker。
• 你想预缓存文件。
• 在路由方面有更复杂的需求。
• 你想service worker与其他API（例如，Web Push）一起使用。

:x:什么时候不使用 injectManifest

• 你想用最简单的方式把service worker放到你的站点。

copyLibraries

如果你想使用 injectManifest 模式，并且想把Workbox库托管到你自己的源而不是Workbox CDN上，那么这个模式很有用。

你运行的时候，只需要提供写入路径：

$ workbox copyLibraries third_party/workbox/
复制代码

构建流程集成

为什么Workbox需要与我的构建过程集成？

Workbox项目包含了需要库，它们共同为你的Web App的service worker提供能力。为了有效的去使用这些库，Workbox需要集成到你Web App构建过程中。去确保你的service worker能够有效的去预缓存你Web App上的所有关键的内容，并保持内容数据最新。

构建过程中 workbox-cli 是正确选择么？

如果你现在的构建流程是基于npm 脚本的，那么 workbox-cli 是一个不错的选择。

如果你当前使用Webpack做为构建工具，那么使用 workbox-webback-plugin 是一个更好的选择。

如果你当前使用 Gulp 、 Grunt 或者一些其他基于Node.js构建的工具，那么几成 workbox-build 到你的构建脚本中是一个不错的选择。

如果你没有构建过程，那么在进行workbox预处理之前你需要选一个。记住，手动运行workbox可能会出一些错，因忘记运行而导致访问者看到的是旧的内容。

安装和配置

把 workbox-cli 你为你项目的开发依赖进行安装后，您可以在现有构建过程的npm脚本末尾添加workbox的调用：

package.json：

{
  "scripts": {
    "build": "my-build-script && workbox <mode> <path/to/config.js>"
  }
}
复制代码

使用 generateSW 或者 injectManifest （取决于你的使用方式）来替换 <mode> ，你的配置文件的路径来替换 <path/to/config.js> 。你的配置文件可由 workbox wizard 创建或是手动调整。

配置

generateSW 使用的配置项

下面是 generateSW 使用的配置项列表。

importWorkboxFrom

可选， String ，默认 cdn 。

有效值： cdn ， local ， disabled 。

• cdn ：默认值，使用Google Cloud Storage上的Workbox CDN。
• local ：将所有Workbox运行时库复制到service worker的带版本的目录中，然后配置service worker来使用这些文件。这个选项适用于希望自己托管所有内空，而不以来于Google Cloud Storage CDN的开发者。
• disabled ：将选择退出自动行为。您可以在首选URL上托管Workbox库的本地副本，并通过 importScripts 配置项将正确的路径传递给 workbox-sw.js 。
• 注意：在webpack中，还支持传入对应于包含自定义Workbox运行时库包的webpack块名称的字符串。

例子

importWorkboxFrom: 'local'
复制代码

skipWaiting

可选， Boolean ，默认 false 。

service worker 是否应该跳过 waiting 生命周期阶段，通常与 clientsClaim: true 一起使用。

例子

skipWaiting: true
复制代码

clientsClaim

可选， Boolean ，默认 false 。

service worker在 active 后否应该在激活后立即开始控制任何现有客户端。

例子：

clientsClaim: true
复制代码

runtimeCaching

可选， Object 的 Array ，默认 [] 。

通过传入 urlPatterns 、 handlers 和可用的一些 options ，在生成的service worker中去添加适当的代码来处理运行时的缓存。

默认情况下处理通过 globPatterns 获取的预缓存的URL请求，不需要写在 runtimeCaching 中。

handler 的值是对应于 workbox.strategies 支持的策略名称。

选项属性可在给定路由实例上配置缓存过期、缓存响应和广播缓存更新插件。

例子

runtimeCaching: [{
    // 匹配包含`api`的任何同源请求。
    urlPattern: /api/,
    // 应用网络优先策略。
    handler: 'networkFirst',
    options: {
      // 超过10s使用缓存做为回退方案。
      networkTimeoutSeconds: 10,
      // 为此路由指定自定义缓存名称。
      cacheName: 'my-api-cache',
      // 配置自定义缓存过期。
      expiration: {
        maxEntries: 5,
        maxAgeSeconds: 60,
      },
      // 配置background sync.
      backgroundSync: {
        name: 'my-queue-name',
        options: {
          maxRetentionTime: 60 * 60,
        },
      },
      // 配置哪些response是可缓存的。
      cacheableResponse: {
        statuses: [0, 200],
        headers: {'x-test': 'true'},
      },
      // 配置广播缓存更新插件。
      broadcastUpdate: {
        channelName: 'my-update-channel',
      },
      // 添加您需要的任何其他逻辑插件。
      plugins: [
        {cacheDidUpdate: () => /* 自定义插件代码 */}
      ],
      // matchOptions 和 fetchOptions 用于配置 handler.
      fetchOptions: {
        mode: 'no-cors',
      },
      matchOptions: {
        ignoreSearch: true,
      },
    },
  }, {
    // 匹配跨域请求，使用以origin开头的正则:
    urlPattern: new RegExp('^https://cors\.example\.com/'),
    handler: 'staleWhileRevalidate',
    options: {
      cacheableResponse: {
        statuses: [0, 200]
      }
    }
  }]
复制代码

navigateFallback

可选， String ，默认 undefined 。

用于创建一个 NavigationRoute ，响应未预缓存的 navigation requests URL。

它适用于SPA场景下通用的App Shell HTML导航请求。

它不适合用作浏览器离线时显示的后备方案。

例子

navigateFallback: '/app-shell'
复制代码

navigateFallbackBlacklist

可选， Array of RegExp ，默认 [] 。

一个可选的正则表达式数组，用于限制配置的 navigateFallback 适用的URL。

如果只将您网站的一部分网址视为SPA的一部分，这将非常有用。

如果同时配置了 navigateFallbackBlacklist 和 navigateFallbackWhitelist ，则 navigateFallbackBlacklist 优先。

例子

// 以`/_`开头或包含`admin`的URL，加入黑名单
navigateFallbackBlacklist: [/^\/_/, /admin/]
复制代码

navigateFallbackWhitelist

可选， Array of RegExp ，默认 [] 。

一个可选的正则表达式数组，用于限制配置的 navigateFallback 适用的URL。

如果只将您网站的一部分网址视为SPA的一部分，这将非常有用。

如果同时配置了 navigateFallbackBlacklist 和 navigateFallbackWhitelist ，则 navigateFallbackBlacklist 优先。

// 以`/pages`开头的URL加入白名单
navigateFallbackWhitelist: [/^\/pages/]
复制代码

importScripts

必填， Array of String 。

传递给生成的service worker中的 importScripts() 的JS文件数组。

如果其中一个导入的文件将 self .__ precacheManifest 变量设置为 ManifestEntrys 数组，那么数组中的条目将会在生成的service worker时自动预先缓存。

当您希望让Workbox创建顶级service worker文件，但希望包含一些其他代码（例如push的事件监听）时，这也很有用。

例子

importScripts: ['push-notifications.abcd1234.js']
复制代码

ignoreUrlParametersMatching

可选， Array of RegExp ，默认 [/^utm_/] 。

在查找预缓存匹配前，将删除与此数组中匹配的任一一个正则表达式。

如果您的用户请求包含用于统计流量来源的URL参数地址，则这个功能非常有用。

例子

// 它会忽略所有参数
ignoreUrlParametersMatching: [/./]
复制代码

directoryIndex

可选， String ，默认 index.html 。

如果以 / 结尾的URL与预缓存的URL航请求不匹配，则此值将附加到URL，并将检查是否与预先缓存匹配。

你应该配置好服务器使用的任何内容，像是目录索引。

例如

directoryIndex: 'index.html'
复制代码

cacheId

可选， String ，默认 null 。

一个可选ID，用于Workbox缓存使用的名称。

主要用于本地开发，可以从相同的 http:// localhost:port 源提供多个站点。

例子

cacheId: 'my-app'
复制代码

offlineGoogleAnalytics

可选， Boolean ，默认 false 。

控制是否包含对 offline Google Analytics 的支持。

injectManifest 使用的配置项

下面是 injectManifest 命令使用的配置项。

swSrc

必填， String 。

除了包含 injectPointRegexp 的匹配项之外，源service worker文件的路径会包含自定义代码。

Node 环境 ： 你的service worker文件应该包含对 workbox.precaching 方法的调用，该方法用于注入预缓存清单。

Webpack 环境 ： 你的service worker文件应引用 self .__ precacheManifest 变量，获取编译后的 ManifestEntrys 列表： workbox.precaching.precacheAndRoute(self.__precacheManifest)

例子

swDest: path.join('src', 'sw.js')
复制代码

injectionPointRegexp

可选， RegExp ，默认 /(\.precacheAndRoute\()\s*\[\s*\]\s*(\))/ 。

默认情况下，使用的 RegExp 将在 swSrc 文件中找到字符串 precacheAndRoute([]) ，并将 [] 数组替换为包含预先缓存的 ManifestEntrys 的数组。

如果你希望将 ManifestEntrys 注入到 swSrc 文件的不同位置，请将其配置为包含两个捕获组的不同 RegExp 。清单数组将被注入捕获组之间。

例子

// 将清单注入到变量赋值中
injectionPointRegexp: new RegExp('(const myManifest =)(;)')
复制代码

两者都使用的配置项

下面选项由两个命令共同使用。

swDest

必填， String 。

构建过程创建的service worker文件的路径和文件名。 在节点中，它将相对于当前工作目录。 在webpack中，它将相对于webpack输出目录。

例子

swDest: path.join('dist', 'sw.js')
复制代码

globDirectory

可选， String ，默认 undefined 。

你希望匹配 globPatterns 的基本目录，相对于当前工作目录。

如果设置了此项，确保配置 globPatterns 项。

例子

// 所有模式相对于当前目录
globDirectory: '.'
复制代码

globFollow

可选， Boolean ，默认 true 。

确保生成预缓存清单时遵循符号链接。

更多信息可以看glob文档的 follow 。

例子

globFollow: false
复制代码

globIgnores

可选， Array of String ，默认 ['node_modules/**/*'] 。

匹配文件的模式，在生成预缓存时，始终排除。

更多信息可以看glob文档的 ignore 。

例子

globIgnores: ['**/ignored.html']
复制代码

globPatterns

可选， Array of String ，默认 ['**/*.{js,css,html}'] （对于workbox-build）或 [] （对于workbox-webpack-plugin）。

任何匹配这些模式的文件将包含在预缓存清单中。

更多信息可以看glob文档。

注意：使用 workbox-webpack-plugin 时通常不需要设置 globPatterns ，默认情况下会自动对webpack构建管道的文件进行预缓存处理。使用webpack插件时，只需在对需要缓存的非webpack资源进行设置。

例子

globPatterns: ['dist/*.{js,png,html,css}']
复制代码

globStrict

可选， Boolean ，默认 true 。

如果为 true ，则在生成预缓存清单出错时将导致生成失败。 如果为 false ，则将跳过有问题的文件。

更多信息可以看glob文档的 strict 。

templatedUrls

可选，带 String 或 Array 的 Object ，默认为 null 。

如果基于服务器端逻辑生成URL，则其内容可能依赖于多个文件或某些其他唯一字符串值。

如果与字符串数组一起使用，它们将被解释为 glob 模式，并且与模式匹配的任何文件的内容，将用于唯一的对URL进行版本。

如果与单个字符串一起使用，它将被解释为你给定URL生成的唯一版本信息。

例如

templatedUrls: {
  '/app-shell': [
    'dev/templates/app-shell.hbs',
    'dev/**/*.css',
    ],
  '/other-page': 'my-version-info',
}
复制代码

maximumFileSizeToCacheInBytes

可选， Number ，默认 2097152 。

这个值可用于确定预缓存的文件的最大值。防止预缓存非常大的文件。

例子

// 限制最大4MB
maximumFileSizeToCacheInBytes: 4 * 1024 * 1024
复制代码

dontCacheBustUrlsMatching

可选， RegExp ，默认 null 。

与此正则表达式匹配的资源，将被假定为通过其URL进行唯一版本化，并且在填充预缓存时避免了正常的HTTP缓存破坏。

虽然不是必需的，但建议如果你现有构建过程已经在每个文件名中插入了 [hash] 值，则会提供一个 RegExp 来检测这些值，因为它会减少预缓存时消耗的带宽量。

例子

dontCacheBustUrlsMatching: /\.\w{8}\./
复制代码

modifyUrlPrefix

可选， String 对象，默认 null 。

前缀的映射，如果存在于预缓存清单中的条目将替换为相应的值。

例如，如果你的Web主机设置与本地文件系统设置不匹配，则可以使用此选项从清单条目中删除或添加路径前缀。

作为具有更大灵活性的替代方法，你可以使用 manifestTransforms 选项并提供一个函数，该函数使用你提供的任何逻辑修改清单中的条目。

例子

modifyUrlPrefix: {
  // 从URL中删除'/ dist'前缀
  '/dist': ''
}
复制代码

manifestTransforms

可选， Array of ManifestTransform ，默认 null 。

一个或多个 ManifestTransform 函数，应用于生成的顺序清单。

如果还指定了 modifyUrlPrefix 或 dontCacheBustUrlsMatching ，则将首先应用相应的转换。

例子

manifestTransforms: [
  // 删除某些URL的基本转换
  (originalManifest) => {
    const manifest = originalManifest.filter(
      (entry) => entry.url !== 'ignored.html');
    // 可选，设置警告消息。
    const warnings = []; 
    return {manifest, warnings};
  }
]
复制代码

博客名称：王乐平博客

CSDN博客地址： blog.csdn.net/lecepin

本作品采用 知识共享署名-非商业性使用-禁止演绎 4.0 国际许可协议 进行许可。