在寫PWA應(yīng)用時，用到WorkBox工具，使用過程中發(fā)現(xiàn)沒有中文的幫助文檔，為了體驗好一些，也為了方便自己和他人查看，在這里翻譯了一下workbox-cli。

---

Workbox CLI 是什么?

Workbox命令行（在workbox-cli包內(nèi)）由workbox的NodeJS程序構(gòu)成，可以運行在Windows、Mac和類UNIX環(huán)境下。workbox-cli包含了workbox-build模塊，并提供了一個通過靈活配置，將Workbox集成到命令行構(gòu)建過程的簡單方法。

---

安裝 CLI

安裝這個CLI很簡單，只需要在終端中運行以下命令。

NPM:

$ npm install workbox-cli --global

YARN:

$ yarn global add workbox-cli

---

CLI模式

CLI有4個不同的模式：

• wizard: 通過步驟向?qū)槟愕捻椖堪惭bWorkbox。
• generateSW: 生成一個完整的service worker。
• injectManifest: 將資源注入到你的項目precache中。
• copyLibraries: 復(fù)制Workbox庫到指定目錄。

wizard

Workbox的wizard會詢問你本地的安裝目錄和你想哪些文件預(yù)緩存的一系列問題。你的回答會生成一個配置文件，用于generateSW模式時使用。

大多數(shù)開發(fā)者只會運行一次workbox wizard，你可以使用任何構(gòu)建配置支持的選項去手動修改初始化生成的配置文件。

使用wizard：

$ workbox wizard

generateSW

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

只需要運行下面命令：

$ workbox generateSW path/to/config.js

Workbox內(nèi)置的預(yù)緩存和運行時緩存功能，不需要再去手動定制他們的service worker的行為，推薦使用generateSW模式。

?什么時候使用generateSW

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

?什么時候不使用generateSW

• 你想使用一些其他的Service Worker特性。
• 你想導(dǎo)入其他腳本或者添加其他邏輯。

injectManifest

對于想要更多控制最終生成的service worker文件的開發(fā)者可以使用injectManifest模式。這個模式需要你有一個存在的service worker文件（文件位置在config.js中指定）。

運行workbox injectManifest時，它會在你的源service worker文件中找指定的字符串（默認(rèn) precaching.precacheAndRoute([]）。它將空數(shù)組替換為precache的URL列表，并將service worker寫到config.js配置項中指定的目標(biāo)位置。在源service worker文件中的其他代碼保持不變。

可以這樣使用：

$ workbox injectManifest path/to/config.js

?什么時候使用injectManifest

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

?什么時候不使用injectManifest

• 你想用最簡單的方式把service worker放到你的站點。

copyLibraries

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

你運行的時候，只需要提供寫入路徑：

$ workbox copyLibraries third_party/workbox/

---

構(gòu)建流程集成

為什么Workbox需要與我的構(gòu)建過程集成？

Workbox項目包含了需要庫，它們共同為你的Web App的service worker提供能力。為了有效的去使用這些庫，Workbox需要集成到你Web App構(gòu)建過程中。去確保你的service worker能夠有效的去預(yù)緩存你Web App上的所有關(guān)鍵的內(nèi)容，并保持內(nèi)容數(shù)據(jù)最新。

構(gòu)建過程中workbox-cli是正確選擇么？

如果你現(xiàn)在的構(gòu)建流程是基于npm 腳本的，那么workbox-cli是一個不錯的選擇。

如果你當(dāng)前使用Webpack做為構(gòu)建工具，那么使用workbox-webback-plugin是一個更好的選擇。

如果你當(dāng)前使用Gulp、Grunt或者一些其他基于Node.js構(gòu)建的工具，那么幾成workbox-build到你的構(gòu)建腳本中是一個不錯的選擇。

如果你沒有構(gòu)建過程，那么在進(jìn)行workbox預(yù)處理之前你需要選一個。記住，手動運行workbox可能會出一些錯，因忘記運行而導(dǎo)致訪問者看到的是舊的內(nèi)容。

安裝和配置

把workbox-cli你為你項目的開發(fā)依賴進(jìn)行安裝后，您可以在現(xiàn)有構(gòu)建過程的npm腳本末尾添加workbox的調(diào)用：

package.json：

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

使用generateSW或者injectManifest（取決于你的使用方式）來替換<mode>，你的配置文件的路徑來替換<path/to/config.js>。你的配置文件可由workbox wizard創(chuàng)建或是手動調(diào)整。

---

配置

generateSW使用的配置項

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

importWorkboxFrom

可選，String，默認(rèn)cdn。

有效值： cdn，local，disabled。

• cdn：默認(rèn)值，使用Google Cloud Storage上的Workbox CDN。
• local：將所有Workbox運行時庫復(fù)制到service worker的帶版本的目錄中，然后配置service worker來使用這些文件。這個選項適用于希望自己托管所有內(nèi)空，而不以來于Google Cloud Storage CDN的開發(fā)者。
• disabled：將選擇退出自動行為。您可以在首選URL上托管Workbox庫的本地副本，并通過importScripts配置項將正確的路徑傳遞給workbox-sw.js。
• 注意：在webpack中，還支持傳入對應(yīng)于包含自定義Workbox運行時庫包的webpack塊名稱的字符串。

例子

importWorkboxFrom: 'local'

skipWaiting

可選，Boolean，默認(rèn)false。

service worker 是否應(yīng)該跳過waiting生命周期階段，通常與clientsClaim: true一起使用。

例子

skipWaiting: true

clientsClaim

可選，Boolean，默認(rèn)false。

service worker在active后否應(yīng)該在激活后立即開始控制任何現(xiàn)有客戶端。

例子：

clientsClaim: true

runtimeCaching

可選，Object的Array，默認(rèn)[]。

通過傳入urlPatterns、handlers和可用的一些options，在生成的service worker中去添加適當(dāng)?shù)拇a來處理運行時的緩存。

默認(rèn)情況下處理通過globPatterns獲取的預(yù)緩存的URL請求，不需要寫在runtimeCaching中。

handler的值是對應(yīng)于workbox.strategies支持的策略名稱。

選項屬性可在給定路由實例上配置緩存過期、緩存響應(yīng)和廣播緩存更新插件。

例子

runtimeCaching: [{// 匹配包含`api`的任何同源請求。urlPattern: /api/,// 應(yīng)用網(wǎng)絡(luò)優(yōu)先策略。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，默認(rèn)undefined。

用于創(chuàng)建一個NavigationRoute，響應(yīng)未預(yù)緩存的navigation requestsURL。

它適用于SPA場景下通用的App Shell HTML導(dǎo)航請求。

它不適合用作瀏覽器離線時顯示的后備方案。

例子

navigateFallback: '/app-shell'

navigateFallbackBlacklist

可選，Array of RegExp，默認(rèn)[]。

一個可選的正則表達(dá)式數(shù)組，用于限制配置的navigateFallback適用的URL。

如果只將您網(wǎng)站的一部分網(wǎng)址視為SPA的一部分，這將非常有用。

如果同時配置了navigateFallbackBlacklist和navigateFallbackWhitelist，則navigateFallbackBlacklist優(yōu)先。

例子

// 以`/_`開頭或包含`admin`的URL，加入黑名單 navigateFallbackBlacklist: [/^\/_/, /admin/]

navigateFallbackWhitelist

可選，Array of RegExp，默認(rèn)[]。

一個可選的正則表達(dá)式數(shù)組，用于限制配置的navigateFallback適用的URL。

如果只將您網(wǎng)站的一部分網(wǎng)址視為SPA的一部分，這將非常有用。

如果同時配置了navigateFallbackBlacklist和navigateFallbackWhitelist，則navigateFallbackBlacklist優(yōu)先。

// 以`/pages`開頭的URL加入白名單 navigateFallbackWhitelist: [/^\/pages/]

importScripts

必填，Array of String。

傳遞給生成的service worker中的importScripts()的JS文件數(shù)組。

如果其中一個導(dǎo)入的文件將self .__ precacheManifest變量設(shè)置為ManifestEntrys數(shù)組，那么數(shù)組中的條目將會在生成的service worker時自動預(yù)先緩存。

當(dāng)您希望讓W(xué)orkbox創(chuàng)建頂級service worker文件，但希望包含一些其他代碼（例如push的事件監(jiān)聽）時，這也很有用。

例子

importScripts: ['push-notifications.abcd1234.js']

ignoreUrlParametersMatching

可選，Array of RegExp，默認(rèn)[/^utm_/]。

在查找預(yù)緩存匹配前，將刪除與此數(shù)組中匹配的任一一個正則表達(dá)式。

如果您的用戶請求包含用于統(tǒng)計流量來源的URL參數(shù)地址，則這個功能非常有用。

例子

// 它會忽略所有參數(shù) ignoreUrlParametersMatching: [/./]

directoryIndex

可選，String，默認(rèn)index.html。

如果以/結(jié)尾的URL與預(yù)緩存的URL航請求不匹配，則此值將附加到URL，并將檢查是否與預(yù)先緩存匹配。

你應(yīng)該配置好服務(wù)器使用的任何內(nèi)容，像是目錄索引。

例如

directoryIndex: 'index.html'

cacheId

可選，String，默認(rèn)null。

一個可選ID，用于Workbox緩存使用的名稱。

主要用于本地開發(fā)，可以從相同的http:// localhost:port源提供多個站點。

例子

cacheId: 'my-app'

offlineGoogleAnalytics

可選，Boolean，默認(rèn)false。

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

---

injectManifest使用的配置項

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

swSrc

必填，String。

除了包含injectPointRegexp的匹配項之外，源service worker文件的路徑會包含自定義代碼。

Node 環(huán)境：
你的service worker文件應(yīng)該包含對workbox.precaching方法的調(diào)用，該方法用于注入預(yù)緩存清單。

Webpack 環(huán)境：
你的service worker文件應(yīng)引用self .__ precacheManifest變量，獲取編譯后的ManifestEntrys列表：
workbox.precaching.precacheAndRoute(self.__precacheManifest)

例子

swDest: path.join('src', 'sw.js')

injectionPointRegexp

可選， RegExp，默認(rèn)/(\.precacheAndRoute\()\s*\[\s*\]\s*(\))/。

默認(rèn)情況下，使用的RegExp將在swSrc文件中找到字符串precacheAndRoute([])，并將[]數(shù)組替換為包含預(yù)先緩存的ManifestEntrys的數(shù)組。

如果你希望將ManifestEntrys注入到swSrc文件的不同位置，請將其配置為包含兩個捕獲組的不同RegExp。清單數(shù)組將被注入捕獲組之間。

例子

// 將清單注入到變量賦值中 injectionPointRegexp: new RegExp('(const myManifest =)(;)')

---

兩者都使用的配置項

下面選項由兩個命令共同使用。

swDest

必填，String。

構(gòu)建過程創(chuàng)建的service worker文件的路徑和文件名。 在節(jié)點中，它將相對于當(dāng)前工作目錄。 在webpack中，它將相對于webpack輸出目錄。

例子

swDest: path.join('dist', 'sw.js')

globDirectory

可選，String，默認(rèn)undefined。

你希望匹配globPatterns的基本目錄，相對于當(dāng)前工作目錄。

如果設(shè)置了此項，確保配置globPatterns項。

例子

// 所有模式相對于當(dāng)前目錄 globDirectory: '.'

globFollow

可選，Boolean，默認(rèn)true。

確保生成預(yù)緩存清單時遵循符號鏈接。

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

例子

globFollow: false

globIgnores

可選，Array of String，默認(rèn)['node_modules/**/*']。

匹配文件的模式，在生成預(yù)緩存時，始終排除。

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

例子

globIgnores: ['**/ignored.html']

globPatterns

可選，Array of String，默認(rèn)['**/*.{js,css,html}']（對于workbox-build）或[]（對于workbox-webpack-plugin）。

任何匹配這些模式的文件將包含在預(yù)緩存清單中。

更多信息可以看glob文檔。

注意：使用workbox-webpack-plugin時通常不需要設(shè)置globPatterns，默認(rèn)情況下會自動對webpack構(gòu)建管道的文件進(jìn)行預(yù)緩存處理。使用webpack插件時，只需在對需要緩存的非webpack資源進(jìn)行設(shè)置。

例子

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

globStrict

可選，Boolean，默認(rèn)true。

如果為true，則在生成預(yù)緩存清單出錯時將導(dǎo)致生成失敗。 如果為false，則將跳過有問題的文件。

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

templatedUrls

可選，帶String或Array的Object，默認(rèn)為null。

如果基于服務(wù)器端邏輯生成URL，則其內(nèi)容可能依賴于多個文件或某些其他唯一字符串值。

如果與字符串?dāng)?shù)組一起使用，它們將被解釋為glob模式，并且與模式匹配的任何文件的內(nèi)容，將用于唯一的對URL進(jìn)行版本。

如果與單個字符串一起使用，它將被解釋為你給定URL生成的唯一版本信息。

例如

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

maximumFileSizeToCacheInBytes

可選，Number，默認(rèn)2097152。

這個值可用于確定預(yù)緩存的文件的最大值。防止預(yù)緩存非常大的文件。

例子

// 限制最大4MB maximumFileSizeToCacheInBytes: 4 * 1024 * 1024

dontCacheBustUrlsMatching

可選，RegExp，默認(rèn)null。

與此正則表達(dá)式匹配的資源，將被假定為通過其URL進(jìn)行唯一版本化，并且在填充預(yù)緩存時避免了正常的HTTP緩存破壞。

雖然不是必需的，但建議如果你現(xiàn)有構(gòu)建過程已經(jīng)在每個文件名中插入了[hash]值，則會提供一個RegExp來檢測這些值，因為它會減少預(yù)緩存時消耗的帶寬量。

例子

dontCacheBustUrlsMatching: /\.\w{8}\./

modifyUrlPrefix

可選，String對象，默認(rèn)null。

前綴的映射，如果存在于預(yù)緩存清單中的條目將替換為相應(yīng)的值。

例如，如果你的Web主機(jī)設(shè)置與本地文件系統(tǒng)設(shè)置不匹配，則可以使用此選項從清單條目中刪除或添加路徑前綴。

作為具有更大靈活性的替代方法，你可以使用manifestTransforms選項并提供一個函數(shù)，該函數(shù)使用你提供的任何邏輯修改清單中的條目。

例子

modifyUrlPrefix: {// 從URL中刪除'/ dist'前綴'/dist': '' }

manifestTransforms

可選，Array of ManifestTransform，默認(rèn)null。

一個或多個ManifestTransform函數(shù)，應(yīng)用于生成的順序清單。

如果還指定了modifyUrlPrefix或dontCacheBustUrlsMatching，則將首先應(yīng)用相應(yīng)的轉(zhuǎn)換。

例子

manifestTransforms: [// 刪除某些URL的基本轉(zhuǎn)換(originalManifest) => {const manifest = originalManifest.filter((entry) => entry.url !== 'ignored.html');// 可選，設(shè)置警告消息。const warnings = []; return {manifest, warnings};} ]

---

博客名稱：王樂平博客

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

本作品采用知識共享署名-非商業(yè)性使用-禁止演繹 4.0 國際許可協(xié)議進(jìn)行許可。

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。