從 Workbox v5 遷移至 v6

本指南著重於 Workbox v6 的破壞性變更，並提供從 Workbox v5 升級時您必須進行的變更。

破壞性變更

工作箱核心

workbox-core 中的 skipWaiting() 方法不會再新增至 install 處理常式，等同於僅呼叫 self.skipWaiting()

從現在起，請改用 self.skipWaiting()，因為 skipWaiting() 可能會在 Workbox v7 中移除。

預先快取

  • 與 HTTP 重新導向對應的網址跨來源 HTML 文件無法再用於滿足 workbox-precaching 的導覽要求。這種狀況通常較為罕見。
  • 現在查詢特定要求的預快取回應時，workbox-precaching 會忽略 fbclid 網址查詢參數。
  • PrecacheController 建構函式現在接受具有特定屬性的物件做為參數，而非字串。這個物件支援下列屬性：cacheName (用途與傳入建構函式 v5 的字串相同)、plugins (取代 v5 中的 addPlugins() 方法) 和 fallbackToNetwork (取代傳遞至 createHandler() 的類似選項和 v5 中的 `createHandlerBoundToURL())。
  • PrecacheController 的 install() 和 activate() 方法現在只接受一個參數，該參數應分別設為對應的 InstallEvent 或 ActivateEvent。
  • addRoute() 方法已從 PrecacheController 中移除。新的 PrecacheRoute 類別可用於建立之後您可以註冊的路徑。
  • precacheAndRoute() 方法已從 PrecacheController 中移除。(仍是 workbox-precaching 模組匯出的靜態輔助方法)。由於系統可以改用 PrecacheRoute，因此已遭移除。
  • createMatchCalback() 方法已從 PrecacheController 中移除。請改用新的 PrecacheRoute。
  • createHandler() 方法已從 PrecacheController 中移除。PrecacheController 物件的 strategy 屬性可以用於處理要求。
  • createHandler() 靜態匯出已從 workbox-precaching 模組中移除。若是如此，開發人員應建構 PrecacheController 執行個體並使用其 strategy 屬性。
  • 向 precacheAndRoute() 註冊的路徑現在是「實際」路徑，會使用 workbox-routing 的 Router 類別。如果交錯呼叫 registerRoute() 和 precacheAndRoute()，這可能會導致路徑的評估順序不同。

工作箱路由

setDefaultHandler() 方法現在接受與所套用 HTTP 方法相對應的選用第二個參數，該參數預設為 'GET'。

  • 如果您使用 setDefaultHandler()，且所有要求都設為 GET，則不需要進行任何變更。
  • 如果您提出的是 GET 以外的要求 (POST、PUT 等)，setDefaultHandler() 不會再導致這些要求相符。

建構設定

workbox-build 和 workbox-cli 中 getManifest 和 injectManifest 模式的 mode 選項不應受到支援，因此已移除。這不適用於 workbox-webpack-plugin，其 InjectManifest 外掛程式支援 mode。

建構工具需要 Node.js v10 以上版本

workbox-webpack-plugin、workbox-build 和 workbox-cli 不再支援 v10 之前的 Node.js 版本。如果您執行的是 v8 之前的 Node.js 版本，請將執行階段更新為支援的版本。

全新改善項目

工作箱策略

Workbox v6 推出了可讓第三方開發人員定義自己的 Workbox 策略的新方法。這可確保第三方開發人員能夠完全依照自身需求擴充 Workbox。

新 Strategy 基礎類別

在 v6 中，所有 Workbox 策略類別都必須擴充新的 Strategy 基礎類別。所有的內建策略都已經過重新撰寫，以因應這種需求。

Strategy 基礎類別負責以下兩項主要工作：

  • 叫用所有策略處理常式 (例如開始、回應和結束) 通用的外掛程式生命週期回呼。
  • 建立「處理常式」執行個體，用於管理策略所處理的每個要求的狀態。

全新「handler」類別

我們之前曾呼叫 fetchWrapper 和 cacheWrapper 的內部模組，顧名思義，會將各種擷取和快取 API 與掛鉤納入其生命週期中。這項機制目前允許外掛程式執行，但開發人員不會得知。

新的「handler」類別 StrategyHandler 會公開這些方法，讓自訂策略能夠呼叫 fetch() 或 cacheMatch()，並自動叫用任何新增至策略執行個體的外掛程式。

這個類別也可讓開發人員根據策略，新增可能專屬的自訂生命週期回呼，而且將「直接」搭配現有的外掛程式介面使用。

新增外掛程式生命週期狀態

Workbox v5 中的外掛程式是無狀態。這表示如果對 /index.html 的要求同時觸發 requestWillFetch 和 cachedResponseWillBeUsed 回呼，這兩個回呼就無法相互通訊，甚至會知道這些回呼是由相同要求所觸發。

在第 6 版中，所有外掛程式回呼也會傳遞新的 state 物件。此狀態物件在這個特定外掛程式物件和此特定策略叫用 (例如對 handle() 的呼叫) 中是唯一的。這樣一來，開發人員就能撰寫外掛程式，讓回呼根據同一個外掛程式中的其他回呼有條件執行特定動作 (例如計算執行 requestWillFetch 和 fetchDidSucceed 或 fetchDidFail 之間的時間差異)。

新增外掛程式生命週期回呼

新增外掛程式生命週期回呼，讓開發人員充分運用外掛程式生命週期狀態：

  • handlerWillStart：在任何處理常式邏輯開始執行前呼叫。此回呼可用來設定初始處理常式狀態 (例如記錄開始時間)。
  • handlerWillRespond：在策略 handle() 方法傳回回應之前呼叫。您可以在將回應傳迴路徑處理常式或其他自訂邏輯之前，使用這個回呼修改回應。
  • handlerDidRespond：在策略的 handle() 方法傳回回應後呼叫。這個回呼可用於記錄任何最終回應詳細資料，例如在其他外掛程式所做的變更後。
  • handlerDidComplete：在這項策略的叫用作業均完成所有延長生命週期承諾的情況下，便會呼叫此方法。此回呼可用來回報任何必須等到處理常式完成後才能計算的資料 (例如快取命中狀態、快取延遲時間、網路延遲時間)。
  • handlerDidError：如果處理常式無法從任何來源提供有效的回應，就會呼叫 。這個回呼可用來提供「備用」內容，做為網路錯誤的替代方案。

開發人員實作專屬策略時，不必擔心叫用這些回呼，由新的 Strategy 基礎類別處理。

更準確的處理常式 TypeScript 類型

各種回呼方法的 TypeScript 定義已正規化。對於使用 TypeScript 並自行編寫程式碼實作或呼叫處理常式的開發人員而言，這應該能帶來更好的體驗。

工作箱視窗

新增訊息 SkipWaiting() 方法

已將新方法 messageSkipWaiting() 新增至 workbox-window 模組，以簡化告知「等待中」Service Worker 的流程。並改善了以下項目：

  • 它會使用實際標準訊息內文 {type: 'SKIP_WAITING'} 呼叫 postMessage()，讓 Workbox 產生的 Service Worker 會檢查是否觸發 skipWaiting()。
  • 它會選擇正確的「等待中」 Service Worker 來張貼這則訊息，即使該工作站與 workbox-window 註冊的 Service Worker 不同也一樣。

移除「外部」事件，並改用 isExternal 資源

workbox-window 中的所有"external"事件皆已移除，取代 isExternal 屬性設為 true 的「一般」事件。這樣一來，重視這項差異的開發人員仍可偵測到該屬性，而不需要知情的開發人員則可忽略此屬性。

清理工具「為使用者提供重新載入網頁」食譜

受到上述兩項異動的影響，「為使用者提供重新載入網頁」食譜的步驟十分簡單：

MULTI_LINE_CODE_PLACEHOLDER_0

工作箱路由

新的布林值參數 sameOrigin 會傳遞給 workbox-routing 中使用的 matchCallback 函式。如果是同一個來源網址，則會設為 true，否則會設為 False。

這可簡化一些常見的樣板：

MULTI_LINE_CODE_PLACEHOLDER_1

Workbox-expiration 中的 matchOptions

您現在可以在 workbox-expiration 中設定 matchOptions，系統會將該欄位做為 CacheQueryOptions 做為基礎 cache.delete() 呼叫傳遞。(大多數開發人員不需這麼做)。

預先快取

採用工作箱策略

workbox-precaching 已重新編寫以使用 workbox-strategies 做為基礎。這應該不會造成任何破壞性變更，而且可以改善兩個模組存取網路和快取的方式，維持長期一致性。

預先快取現在會逐一處理項目，而非大量處理項目

已更新 workbox-precaching，讓系統一次只要求及快取預先快取資訊清單中一個項目，而不會嘗試一次要求並快取所有項目，而不是嘗試一次要求並快取所有項目 (先讓瀏覽器找出節流限制)。

這應該可以降低預先快取時發生 net::ERR_INSUFFICIENT_RESOURCES 錯誤的可能性，也能降低預先快取與同時網頁應用程式發出的頻寬爭用情況。

PrecacheFallbackPlugin 可讓您更輕鬆地進行離線備份

workbox-precaching 現在包含 PrecacheFallbackPlugin，可實作第 6 版中新增的 handlerDidError 生命週期方法。

這樣一來，當特定策略回應沒有可用的回應時，您就能輕鬆將預先快取的網址指定為備用網址。外掛程式會妥善建構預先快取網址的正確快取金鑰，包括任何所需的修訂版本參數。

以下是當 NetworkOnly 策略無法針對瀏覽要求產生回應 (也就是顯示自訂離線 HTML 網頁) 時，可使用這個函式以回應預先快取 /offline.html 的範例：

MULTI_LINE_CODE_PLACEHOLDER_2

執行階段快取中的 precacheFallback

如果您使用 generateSW 建立 Service Worker，而不是手動編寫 Service Worker，您可以在 runtimeCaching 中使用新的 precacheFallback 設定選項來完成相同目的：

{
  // ... other generateSW config options...
  runtimeCaching: [{
    urlPattern: ({request}) => request.mode === 'navigate',
    handler: 'NetworkOnly',
    options: {
      precacheFallback: {
        // This URL needs to be included in your precache manifest.
        fallbackURL: '/offline.html',
      },
    },
  }],
}

取得協助

我們預期大部分的遷移作業都很直觀。如果您遇到本指南未提及的問題，請在 GitHub 上回報問題通知我們。