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 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博客地址：blog.csdn.net/lecepin

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