本指南著重於 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 上回報問題通知我們。