在寫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模式。

?什么時候使用generateSW

• 你想預緩存文件。
• 你需要一些簡單的運行時配置（例如，配置允許你定義的路由和策略）。

?什么時候不使用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

?什么時候使用injectManifest

• 你想更好的控制service worker。
• 你想預緩存文件。
• 在路由方面有更復雜的需求。
• 你想service worker與其他API（例如，Web Push）一起使用。

?什么時候不使用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 requestsURL。

它適用于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博客地址：http://blog.csdn.net/lecepin

本作品采用知識共享署名-非商業性使用-禁止演繹 4.0 國際許可協議進行許可。

總結

以上是生活随笔為你收集整理的Workbox CLI v3.x 中文版的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。