Workbox-webpack-plugin

Workbox 提供兩個 webpack 外掛程式：一個會為您產生完整的服務工作者，另一個則會產生資產清單，以便將預先快取的資產插入服務工作者檔案。

這些外掛程式會在 workbox-webpack-plugin 模組中實作為兩個類別，分別命名為 GenerateSW 和 InjectManifest。下列問題的答案可協助您選擇要使用的正確外掛程式和設定。

要使用的外掛程式

GenerateSW

GenerateSW 外掛程式會為您建立服務工作者檔案，並將檔案新增至 webpack 資產管道。

使用 GenerateSW 的時機

  • 你想要友善快取檔案。
  • 您有簡單的執行階段快取需求。

不應使用 GenerateSW 的情況

  • 您想使用其他 Service Worker 功能 (例如 Web Push)。
  • 您想匯入其他指令碼，或為自訂快取策略新增其他邏輯。

InjectManifest

InjectManifest 外掛程式會產生要預快取的網址清單，並將該預快取資訊清單加入現有的服務工作者檔案。否則會讓檔案維持原樣。

使用「InjectManifest」的時機

  • 您想進一步控管服務工作者。
  • 您想要預先快取檔案。
  • 您需要自訂路由和策略。
  • 您想將服務工作者與其他平台功能 (例如 Web Push) 搭配使用。

「不」使用 InjectManifest 的情況

  • 您想以最簡單的方式將服務工作者新增至網站。

GenerateSW 外掛程式

您可以將 GenerateSW 外掛程式新增至 webpack 設定，如下所示：

// Inside of webpack.config.js:
const {GenerateSW} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new GenerateSW({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      navigateFallback: '...',
      runtimeCaching: [{
        // Routing via a matchCallback function:
        urlPattern: ({request, url}) => ...,
        handler: '...',
        options: {
          cacheName: '...',
          expiration: {
            maxEntries: ...,
          },
        },
      }, {
        // Routing via a RegExp:
        urlPattern: new RegExp('...'),
        handler: '...',
        options: {
          cacheName: '...',
          plugins: [..., ...],
        },
      }],
      skipWaiting: ...,
    }),
  ],
};

這會產生服務工作者，並為設定中選取的所有 webpack 資產，以及提供的執行階段快取規則，設定預先快取功能。

您可以在參考說明文件找到完整的設定選項。

InjectManifest 外掛程式

您可以將 InjectManifest 外掛程式新增至 webpack 設定，如下所示：

// Inside of webpack.config.js:
const {InjectManifest} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new InjectManifest({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      swSrc: '...',
    }),
  ],
};

系統會根據設定檔擷取的 webpack 素材資源，建立預先快取資訊清單，並將其插入已重新整理及編譯的服務工作者檔案。

如需完整的設定選項，請參閱參考文件。

其他資訊

請參閱 Webpack 說明文件的「Progressive Web Application」(漸進式網頁應用程式應用程式) 一節，瞭解如何在大型 Webpack 版本的環境中使用外掛程式。

類型

GenerateSW

這個類別支援在 webpack 編譯程序中建立新的、可立即使用的服務工作者檔案。

在 webpack 設定的 plugins 陣列中使用 GenerateSW 例項。

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new GenerateSW({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  navigateFallback: '...',
  runtimeCaching: [{
    // Routing via a matchCallback function:
    urlPattern: ({request, url}) => ...,
    handler: '...',
    options: {
      cacheName: '...',
      expiration: {
        maxEntries: ...,
      },
    },
  }, {
    // Routing via a RegExp:
    urlPattern: new RegExp('...'),
    handler: '...',
    options: {
      cacheName: '...',
      plugins: [..., ...],
    },
  }],
  skipWaiting: ...,
});

屬性

GenerateSWConfig

屬性

  • additionalManifestEntries

    (string | ManifestEntry)[] 選填

    除了在建構設定中產生的任何項目外，這也是要預先快取的項目清單。

  • babelPresetEnvTargets

    string[] 選填

    預設值：["chrome >= 56"]

    轉譯服務工作者套件時，要傳遞至 babel-preset-env 的目標。

  • cacheId

    string 選填

    可選 ID，會附加至快取名稱的前方。這項功能主要適用於本機開發作業，因為在這種情況下，多個網站可能會從相同的 http://localhost:port 來源放送。

  • 區塊

    string[] 選填

    應納入預快取資訊清單的一或多個區塊名稱。

  • cleanupOutdatedCaches

    boolean 選填

    預設值：false

    Workbox 應否嘗試找出並刪除舊版 (不相容) 建立的任何預快取內容。

  • clientsClaim

    布林值 選填

    預設值為 false。

    服務工作者是否應在啟用後立即開始控制任何現有用戶端。

  • directoryIndex

    string optional

    如果網址結尾為 / 的網址的導覽要求與預先快取的網址不符，該值會附加至網址，並檢查是否有預先快取比對相符。這項設定應設為網路伺服器用於目錄索引的值。

  • disableDevLogs

    boolean 選填

    預設值：false

  • dontCacheBustURLsMatching

    RegExp 選填

    系統會假設符合此條件的資產是透過其網址單獨建立版本，並且免除填入預先快取時執行的一般 HTTP 快取清除。雖然不是必要，但如果您現有的建構程序已在每個檔案名稱中插入 [hash] 值，建議您提供可偵測該值的規則運算式，因為這樣可減少預先快取時使用的頻寬。

  • 排除

    (string | RegExp | function)[] 選填

    用於從預快取資訊清單中排除資產的一或多個指定項目。這會依照相同的規則和 webpack 的標準 exclude 選項解讀。如未提供，預設值為 [/\.map$/, /^manifest.*\.js$]。

  • excludeChunks

    string[] 選填

    一或多個區塊名稱，其對應的輸出檔案應從預快取資訊清單中排除。

  • ignoreURLParametersMatching

    RegExp[] 選填

    系統會先移除與此陣列中任一 RegExp 相符的搜尋參數名稱，再尋找快取前比對結果。如果使用者可能會要求含有網址參數的網址 (例如用於追蹤流量來源的網址參數)，這項功能就很實用。如未提供，則預設值為 [/^utm_/, /^fbclid$/]。

  • importScripts

    string[] 選填

    在產生的服務工作者檔案中，應傳遞至 importScripts() 的 JavaScript 檔案清單。如果您想讓 Workbox 建立頂層 Service Worker 檔案，但想加入一些額外的程式碼 (例如推送事件監聽器)，這個方法就很實用。

  • importScriptsViaChunks

    string[] 選填

    一或多個 Webpack 區塊名稱。產生的 Service Worker 會呼叫 importScripts()，將這些區塊的內容納入產生的 Service Worker。

  • 包含

    (string | RegExp | function)[] 選填

    一或多個指定符，用於在預快取資訊清單中加入資產。這會依照相同的規則和 webpack 的標準 include 選項解讀。

  • inlineWorkboxRuntime

    布林值 選填

    預設值為 false。

    是否應將 Workbox 程式庫的執行階段程式碼納入頂層服務工作站，或是將其拆分為需要與服務工作站一併部署的個別檔案。保持執行階段的獨立性，表示使用者在頂層服務工作程變更時，不必重新下載 Workbox 程式碼。

  • manifestEntries

    ManifestEntry[] 選用

  • manifestTransforms

    ManifestTransform[] 選用

    一或多個函式，會依序套用至產生的資訊清單。如果也指定 modifyURLPrefix 或 dontCacheBustURLsMatching，系統會先套用對應的轉換。

  • maximumFileSizeToCacheInBytes

    號碼 選填

    預設值：2097152

    這個值可用來決定預先快取檔案的最大大小。這樣一來，您就不會不小心預先快取可能意外符合其中一個模式的超大檔案。

  • 模式

    string optional

    如果設為「production」，系統會產生經過最佳化的服務工作者套件，其中會排除偵錯資訊。如果未在此處明確設定，系統會使用目前 webpack 編譯作業中設定的 mode 值。

  • modifyURLPrefix

    物件 optional

    將字串前置字串與替換字串值對應的物件。舉例來說，如果網站代管設定與本機檔案系統設定不符，有心人士就能利用這項功能，從資訊清單項目中移除或新增路徑前置字串。您可以使用 manifestTransforms 選項，並提供函式，以便使用您提供的任何邏輯修改資訊清單中的項目，這是另一種更具彈性的做法。

    使用範例：

    // Replace a '/dist/' prefix with '/', and also prepend
// '/static' to every URL.
modifyURLPrefix: {
  '/dist/': '/',
  '': '/static',
}
  • navigateFallback

    string 選填

    預設值為 null。

    如有指定，所有未預先快取的網址導覽要求都會在提供的網址中，以 HTML 執行。您必須傳入預先快取資訊清單列出的 HTML 文件網址。主要用於單一頁面應用程式情境，也就是您希望所有導覽使用通用的 App Shell HTML。

  • navigateFallbackAllowlist

    規則運算式 [] 選填

    規則運算式的選用陣列，可限制所設定 navigateFallback 行為適用的網址。如果只應將網站的一小部分網址視為單一頁面應用程式的一部分，這種做法會很實用。如果您同時設定了 navigateFallbackDenylist 和 navigateFallbackAllowlist，拒絕清單會優先採用。

    注意：系統會在導航期間根據每個到達網頁網址評估這些規則運算式。請避免使用複雜的正規表示式，否則使用者在瀏覽網站時可能會發生延遲。

  • navigateFallbackDenylist

    RegExp[] 選填

    選用規則運算式的陣列，可限制要套用所設 navigateFallback 行為的網址。如果您只想將網站網址的子集視為單頁應用程式的一部分，這個方法就很實用。如果您同時設定 navigateFallbackDenylist 和 navigateFallbackAllowlist，則拒絕清單會優先採用。

    注意：這些規則運算式可能會在導覽期間針對每個目的地網址進行評估。請避免使用複雜的正規表示式，否則使用者在瀏覽網站時可能會發生延遲。

  • navigationPreload

    boolean 選填

    預設值為 false。

    是否要在產生的服務工作者中啟用導覽預先載入功能。設為 true 時，您也必須使用 runtimeCaching 來設定符合導覽要求的適當回應策略，並使用預先載入的回應。

  • offlineGoogleAnalytics

    boolean | GoogleAnalyticsInitializeOptions 選用

    預設值：false

    控制是否納入 離線 Google Analytics 支援功能。如果為 true，系統會將對 workbox-google-analytics 的 initialize() 的呼叫新增至產生的 Service Worker。設為 Object 時，該物件會傳入 initialize() 呼叫，方便您自訂行為。

  • runtimeCaching

    RuntimeCaching[] 選用

    使用 Workbox 的建構工具產生服務工作站時，您可以指定一或多個執行階段快取設定。然後，系統會使用您定義的配對和處理程序設定，將這些呼叫轉譯為 workbox-routing.registerRoute 呼叫。

    如需所有選項，請參閱 workbox-build.RuntimeCaching 說明文件。以下範例顯示典型設定，其中定義了兩個執行階段路徑：

  • skipWaiting

    boolean 選填

    預設值為 false。

    是否向產生的 Service Worker 新增無條件的 skipWaiting() 呼叫。如果是 false，則會改為新增 message 事件監聽器，讓用戶端網頁在等待服務 worker 時呼叫 postMessage({type: 'SKIP_WAITING'})，進而觸發 skipWaiting()。

  • sourcemap

    boolean 選填

    預設值為 true。

    是否要為產生的 Service Worker 檔案建立來源對應。

  • swDest

    string 選填

    預設值："service-worker.js"

    這個外掛程式建立的服務工作者檔案的素材資源名稱。

InjectManifest

這個類別支援編譯透過 swSrc 提供的 Service Worker 檔案，以及插入至該 Service Worker 中，用於根據 webpack 資產管道預先快取的網址和修訂版本資訊。

在 Webpack 設定的 plugins 陣列中使用 InjectManifest 例項。

除了插入資訊清單，這個外掛程式也會使用主要 webpack 設定中的選項，對 swSrc 檔案執行編譯作業。

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new InjectManifest({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  swSrc: '...',
});

屬性

屬性

default

類型

物件

屬性

  • GenerateSW

    查詢

  • InjectManifest

    查詢