Workbox-webpack-plugin

Workbox 提供兩個 webpack 外掛程式，一個可為您產生完整的 Service Worker，另一個則產生要插入至 Service Worker 檔案的預先快取資產清單。

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

要使用的外掛程式

GenerateSW

GenerateSW 外掛程式會為您建立 Service Worker 檔案，並將其新增至 Webpack 資產管道。

使用「GenerateSW」的時機

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

「不」使用 GenerateSW 的時機

  • 您想要使用其他 Service Worker 功能 (例如網路推播)。
  • 您想要匯入其他指令碼，或新增自訂快取策略的其他邏輯。

InjectManifest

InjectManifest 外掛程式會產生要預先快取的網址清單，並將該預先快取資訊清單加入現有的 Service Worker 檔案。否則檔案會保持原樣。

使用「InjectManifest」的時機

  • 您想要進一步控管 Service Worker。
  • 您想要友善載入檔案。
  • 您必須自訂轉送機制和策略。
  • 您想搭配使用服務工作處理程序與其他平台功能 (例如網路推播)。

「不」使用 InjectManifest 的時機

  • 您希望以最簡單的方式在網站中新增 Service Worker。

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 資產和提供的執行階段快取規則，產生具有預先快取設定的 Service Worker。

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

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 資產來建立預先快取資訊清單，並將該資訊清單插入封裝的 Service Worker 檔案。

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

其他資訊

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

類型

GenerateSW

這個類別支援在 Webpack 編譯程序中，建立新的立即可用的 Service Worker 檔案。

在 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"]

    在轉譯 Service Worker 套件時，要傳遞至 babel-preset-env 的目標。

  • cacheId

    字串 選用

    會加在快取名稱前面的選用 ID。這主要適用於在本機開發中，因為多個網站可能會透過同一個 http://localhost:port 來源提供。

  • 區塊

    string[] 選填

    一或多個區塊名稱，其對應的輸出檔案應包含在預載資訊清單中。

  • cleanupOutdatedCaches

    布林值 (選用)

    預設值為 false。

    無論是否應嘗試找出並刪除由較舊且不相容的版本建立的預先快取。

  • clientsClaim

    布林值 (選用)

    預設值為 false。

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

  • directoryIndex

    字串 選用

    如果結尾為 / 的網址瀏覽要求無法與友善快取網址相符，這個值會附加至網址，系統會檢查網址是否與友善快取相符。應設為網路伺服器用於目錄索引的值。

  • disableDevLogs

    布林值 (選用)

    預設值為 false。

  • dontCacheBustURLsMatching

    規則運算式 選用

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

  • 排除

    (string|RegExp|function)[] optional

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

  • excludeChunks

    string[] 選填

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

  • ignoreURLParametersMatching

    RegExp[] 選填

    所有與這個陣列中任一規則運算式相符的搜尋參數名稱都會遭到移除，再尋找友善快取比對。如果使用者要求的網址包含用於追蹤流量來源的網址參數，這個方法就非常實用。如未提供，則預設值為 [/^utm_/, /^fbclid$/]。

  • importScripts

    string[] 選填

    應在產生的 Service Worker 檔案中，傳送至 importScripts() 的 JavaScript 檔案清單。如果您想讓 Workbox 建立頂層 Service Worker 檔案，但想要加入某些額外的程式碼 (例如推送事件監聽器)，這項功能就非常實用。

  • importScriptsViaChunks

    string[] 選填

    一或多個 Webpack 區塊的名稱。這些區塊的內容會透過呼叫 importScripts()，包含在產生的 Service Worker 中。

  • 包含

    (string|RegExp|function)[] optional

    用來在預先快取資訊清單中加入資產的一或多個指定碼。這會遵循與 webpack 標準 include 選項相同的規則。

  • inlineWorkboxRuntime

    布林值 (選用)

    預設值為 false。

    是否要將 Workbox 程式庫的執行階段程式碼納入頂層服務工作站，或分割成必須與 Service Worker 一併部署的獨立檔案。讓執行階段獨立運作，表示每當您的頂層 Service Worker 變更時，使用者都不必重新下載 Workbox 程式碼。

  • manifestEntries

    ManifestEntry[] 選填

  • manifestTransforms

    ManifestTransform[] 選用

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

  • maximumFileSizeToCacheInBytes

    數字 選填

    預設值為 2097152

    這個值可用於決定預載檔案的大小上限。這可避免您不小心預先快取了可能意外符合其中一個模式的超大型檔案。

  • 模式

    字串 選用

    如果設為「production」，系統就會產生排除偵錯資訊的最佳化 Service Worker 套件。如果此處未明確設定，系統會使用目前 webpack 編譯中設定的 mode 值。

  • modifyURLPrefix

    物件選用

    物件對應字串的前置字串與替換的字串值。這可用於例如在資訊清單項目中移除或新增路徑前置字串 (如果網站代管設定與本機檔案系統設定不符)。做為替代彈性空間的替代方法，您可以使用 manifestTransforms 選項，並提供一個函式，使用您提供的任何邏輯來修改資訊清單中的項目。

    使用範例：

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

    字串 選用

    預設值為 null。

    如有指定，則未友善載入網址的所有導覽要求都會在提供的網址中使用 HTML 執行。您必須傳入預先快取資訊清單中所列的 HTML 文件網址。這個屬性應用於單一頁面應用程式，也就是您希望所有導覽都可使用常見的應用程式 Shell HTML。

  • navigateFallbackAllowlist

    RegExp[] 選填

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

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

  • navigateFallbackDenylist

    RegExp[] 選填

    (選用) 規則運算式陣列，用於限制已設定 navigateFallback 行為的網址。如果只應將網站的部分網址視為單一頁面應用程式的一部分，這種做法就相當實用。如果同時設定 navigateFallbackDenylist 和 navigateFallbackAllowlist，系統會優先採用拒絕清單。

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

  • navigationPreload

    布林值 (選用)

    預設值為 false。

    指定是否要在產生的 Service Worker 中啟用導覽預先載入。設為 true 時，您還必須使用 runtimeCaching 來設定符合導覽要求的適當回應策略，並使用預先載入的回應。

  • offlineGoogleAnalytics

    boolean|GoogleAnalyticsInitializeOptions optional

    預設值為 false。

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

  • runtimeCaching

    RuntimeCaching[] 選用

    使用 Workbox 的建構工具產生 Service Worker 時，您可以指定一或多項執行階段快取設定。接著，這些系統會使用您定義的比對和處理常式設定，轉譯為 workbox-routing.registerRoute 呼叫。

    如需所有選項，請參閱 workbox-build.RuntimeCaching 說明文件。以下範例為定義了兩個執行階段路徑的一般設定：

  • skipWaiting

    布林值 (選用)

    預設值為 false。

    是否要對產生的 Service Worker 新增對 skipWaiting() 無條件的呼叫。如果設為 false，系統會改為新增 message 事件監聽器，讓用戶端頁面在等待的 Service Worker 上呼叫 postMessage({type: 'SKIP_WAITING'})，藉此觸發 skipWaiting()。

  • 來源對應

    布林值 (選用)

    預設值為 true

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

  • swDest

    字串 選用

    預設值為 "service-worker.js"

    這個外掛程式建立的 Service Worker 檔案資產名稱。

InjectManifest

這個類別支援編譯透過 swSrc 提供的 Service Worker 檔案，並可根據 webpack 資產管道，將網址和修訂版本資訊插入該 Service Worker，以便進行預先快取。

在 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

    項查詢