Workbox-build

workbox-build 模組會整合到以節點為基礎的建構程序中，並產生完整的 Service Worker，或只產生要預先快取的資產清單，供現有 Service Worker 使用。

大多數開發人員會使用 generateSW 和 injectManifest 這兩種模式。回答下列問題，有助於選擇合適的模式和設定。

要使用的模式

generateSW

generateSW 模式會為您建立服務工作人員檔案，並透過設定選項自訂該檔案，然後寫入磁碟。

使用時機 generateSW

  • 您想要預先快取檔案。
  • 您只需要簡單的執行階段快取。

不應使用 generateSW 的情況

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

injectManifest

injectManifest 模式會產生要預先快取的網址清單，並將該預先快取資訊清單新增至現有的服務工作站檔案。否則檔案會維持原狀。

使用時機 injectManifest

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

不應使用 injectManifest 的情況

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

generateSW 模式

您可以在節點式建構指令碼中使用 generateSW 模式，並使用最常見的設定選項，如下所示：

// Inside of build.js:
const {generateSW} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
generateSW({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  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: ...,
  swDest: '...',
}).then(({count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while generating a service worker:',
      warnings.join('\n')
    );
  }

  console.log(`Generated a service worker, which will precache ${count} files, totaling ${size} bytes.`);
});

這會為設定檔和提供的執行階段快取規則所選取的所有檔案，產生預先快取設定的 Service Worker。

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

injectManifest 模式

您可以在節點式建構指令碼中使用 injectManifest 模式，並使用最常見的設定選項，如下所示：

// Inside of build.js:
const {injectManifest} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
injectManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
  swDest: '...',
  swSrc: '...',
}).then(({count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while injecting the manifest:',
      warnings.join('\n')
    );
  }

  console.log(`Injected a manifest which will precache ${count} files, totaling ${size} bytes.`);
});

這會根據設定檔擷取的檔案建立預先快取資訊清單，並將其插入現有的 Service Worker 檔案。

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

其他模式

我們預期 generateSW 或 injectManifest 可滿足大多數開發人員的需求。不過，workbox-build 支援另一種模式，可能適合特定用途。

getManifest 模式

這在概念上與 injectManifest 模式類似，但不會將資訊清單新增至來源服務工作站檔案，而是傳回資訊清單項目陣列，以及項目數量和總大小的相關資訊。

您可以在節點式建構指令碼中使用 injectManifest 模式，並使用最常見的設定選項，如下所示：

// Inside of build.js:
const {getManifest} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
getManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
}).then(({manifestEntries, count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while getting the manifest:',
      warnings.join('\n')
    );
  }

  // Do something with the manifestEntries, and potentially log count and size.
});

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

類型

BasePartial

屬性

  • additionalManifestEntries

    (string | ManifestEntry)[] 選用

    除了建構設定產生的項目外，還有一份要預先快取的項目清單。

  • dontCacheBustURLsMatching

    規則運算式 選填

    系統會假設符合這項條件的資產是透過網址進行版本控制，因此在填入預先快取時，會免除正常 HTTP 快取清除作業。雖然不是必要條件，但建議您提供可偵測該值的 RegExp，因為這樣可減少預先快取時消耗的頻寬。[hash]

  • manifestTransforms

    ManifestTransform[] 選用

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

  • maximumFileSizeToCacheInBytes

    數字 選填

    預設值為：2097152

    這個值可用於判斷預先快取的檔案大小上限。這樣可避免您不慎預先快取可能意外符合其中一個模式的超大檔案。

  • modifyURLPrefix

    object 選填

    這個物件會將字串前置字元對應至替換字串值。舉例來說，如果網路代管設定與本機檔案系統設定不符，您可以使用這項功能從資訊清單項目中移除或新增路徑前置字串。如要使用更具彈性的替代方案，可以採用 manifestTransforms 選項，並提供函式，透過您提供的任何邏輯修改資訊清單中的項目。

    使用範例：

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

BuildResult

類型

Omit<GetManifestResult"manifestEntries"
> & object

屬性

  • filePaths

    string[]

GeneratePartial

屬性

  • babelPresetEnvTargets

    字串陣列 選用

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

    要傳遞至 babel-preset-env 的目標，用於轉譯服務工作人員套件。

  • cacheId

    字串 選填

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

  • cleanupOutdatedCaches

    布林值 選填

    預設值為 false

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

  • clientsClaim

    布林值 選填

    預設值為 false

    服務工作人員是否應在啟動後，立即開始控管任何現有用戶端。

  • directoryIndex

    字串 選填

    如果以 / 結尾的網址導覽要求無法與預先快取的網址相符，系統會將這個值附加至網址，並檢查是否與預先快取的網址相符。這項設定應與網路伺服器用於目錄索引的內容一致。

  • disableDevLogs

    布林值 選填

    預設值為 false

  • ignoreURLParametersMatching

    RegExp[] 選填

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

  • importScripts

    字串陣列 選用

    應傳遞至所產生服務工作人員檔案內 importScripts() 的 JavaScript 檔案清單。如果您想讓 Workbox 建立頂層服務工作人員檔案，但又想加入一些額外程式碼 (例如推送事件監聽器)，這項功能就非常實用。

  • inlineWorkboxRuntime

    布林值 選填

    預設值為 false

    是否應將 Workbox 程式庫的執行階段程式碼納入頂層服務工作人員，或分成個別檔案，與服務工作人員一併部署。將執行階段分開，表示使用者不必在每次頂層服務工作人員變更時，重新下載 Workbox 程式碼。

  • 模式

    字串 選填

    預設值為「production」

    如果設為「production」，系統會產生排除偵錯資訊的最佳化 Service Worker 套件。如果未在此處明確設定，系統會使用 process.env.NODE_ENV 值，如果該值不存在，則會改用 'production'。

  • navigateFallback

    字串 選填

    預設值為：null

    如果指定了這個屬性，系統會使用提供的網址中的 HTML，滿足所有導覽要求 (網址並未預先快取)。您必須傳遞預先快取資訊清單中列出的 HTML 文件網址。這項功能適用於單頁應用程式情境，您希望所有導覽都使用通用的 App Shell HTML。

  • navigateFallbackAllowlist

    RegExp[] 選填

    選用規則運算式陣列，可限制設定的 navigateFallback 行為適用的網址。如果只有部分網站網址應視為單頁應用程式的一部分，這項功能就非常實用。如果同時設定 navigateFallbackDenylist 和 navigateFallbackAllowlist，系統會優先採用拒絕清單。

    注意：系統可能會在導覽期間，針對每個目的地網址評估這些 RegExps。請避免使用複雜的 RegExps，否則使用者瀏覽網站時可能會遇到延遲問題。

  • navigateFallbackDenylist

    RegExp[] 選填

    選用規則運算式陣列，可限制設定的 navigateFallback 行為適用的網址。如果只有部分網站網址應視為單頁應用程式，這項功能就非常實用。如果同時設定 navigateFallbackDenylist 和 navigateFallbackAllowlist，系統會優先採用拒絕清單。

    注意：系統可能會在導覽期間，針對每個目的地網址評估這些 RegExps。請避免使用複雜的 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

    是否要將無條件呼叫新增至產生的服務工作人員 skipWaiting()。如果是 false，則會改為新增 message 監聽器，讓用戶端網頁透過在等待中的 Service Worker 上呼叫 postMessage({type: 'SKIP_WAITING'})，觸發 skipWaiting()。

  • sourcemap

    布林值 選填

    預設值為 true

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

GenerateSWOptions

類型

BasePartial & GlobPartial & GeneratePartial & RequiredSWDestPartial & OptionalGlobDirectoryPartial

GetManifestOptions

類型

BasePartial & GlobPartial & RequiredGlobDirectoryPartial

GetManifestResult

屬性

  • 數量

    數字

  • manifestEntries

    ManifestEntry[]

  • 大小

    數字

  • 項警告

    string[]

GlobPartial

屬性

  • globFollow

    布林值 選填

    預設值為 true

    決定產生預先快取資訊清單時是否要追蹤符號連結。詳情請參閱glob 說明文件中的 follow 定義。

  • globIgnores

    字串陣列 選用

    預設值為：["**\/node_modules\/**\/*"]

    一組模式，用於比對在產生預先快取資訊清單時一律要排除的檔案。詳情請參閱glob 說明文件中的 ignore 定義。

  • globPatterns

    字串陣列 選用

    預設值為：["**\/*.{js,wasm,css,html}"]

    符合這些模式的檔案會納入預先快取資訊清單。詳情請參閱glob入門指南。

  • templatedURLs

    object 選填

    如果網址是根據某些伺服器端邏輯算繪，其內容可能取決於多個檔案或其他獨特的字串值。這個物件中的鍵是伺服器算繪的網址。如果值是字串陣列，系統會將其解譯為 glob 模式，並使用符合模式的任何檔案內容，為網址建立專屬版本。如果搭配單一字串使用，系統會將其解讀為您為特定網址產生的專屬版本資訊。

InjectManifestOptions

類型

BasePartial & GlobPartial & InjectPartial & RequiredSWDestPartial & RequiredGlobDirectoryPartial

InjectPartial

屬性

  • injectionPoint

    字串 選填

    預設值為："self.__WB_MANIFEST"

    要在 swSrc 檔案中尋找的字串。找到後，系統會以產生的預先快取資訊清單取代。

  • swSrc

    字串

    在建構程序期間讀取的服務工作人員檔案路徑和檔案名稱，相對於目前的工作目錄。

ManifestEntry

屬性

  • 完整性

    字串 選填

  • 修訂

    字串

  • 網址

    字串

ManifestTransform()

workbox-build.ManifestTransform(
  manifestEntries: (ManifestEntry & object)[],
  compilation?: unknown,
): Promise<ManifestTransformResult> | ManifestTransformResult

類型

函式

參數

  • manifestEntries

    (ManifestEntry & object)[]

    • 大小

      數字

  • 合輯

    不明 選填

傳回

ManifestTransformResult

屬性

  • 資訊清單

    (ManifestEntry & object)[]

    • 大小

      數字

  • 項警告

    字串陣列 選用

OptionalGlobDirectoryPartial

屬性

  • globDirectory

    字串 選填

    您要比對的本機目錄 globPatterns。路徑是相對於目前目錄。

RequiredGlobDirectoryPartial

屬性

  • globDirectory

    字串

    您要比對的本機目錄 globPatterns。路徑是相對於目前目錄。

RequiredSWDestPartial

屬性

  • swDest

    字串

    建構程序建立的服務工作人員檔案路徑和檔案名稱，相對於目前的工作目錄。必須以「.js」結尾。

RuntimeCaching

屬性

StrategyName

列舉

「CacheFirst」

「CacheOnly」

「NetworkFirst」

「NetworkOnly」

「StaleWhileRevalidate」

WebpackGenerateSWOptions

類型

BasePartial & WebpackPartial & GeneratePartial & WebpackGenerateSWPartial

WebpackGenerateSWPartial

屬性

  • importScriptsViaChunks

    字串陣列 選用

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

  • swDest

    字串 選填

    預設值為「service-worker.js」

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

WebpackInjectManifestOptions

類型

BasePartial & WebpackPartial & InjectPartial & WebpackInjectManifestPartial

WebpackInjectManifestPartial

屬性

  • compileSrc

    布林值 選填

    預設值為 true

    如果設為 true (預設值)，webpack 會編譯 swSrc 檔案。如果 false，系統不會進行編譯 (且無法使用 webpackCompilationPlugins)。如要將資訊清單插入 JSON 檔案等，請設為 false。

  • swDest

    字串 選填

    這個外掛程式建立的 Service Worker 檔案資產名稱。如果省略，名稱會依據 swSrc 名稱。

  • webpackCompilationPlugins

    any[] 選填

    編譯 swSrc 輸入檔案時要使用的選用 webpack 外掛程式。只有在 compileSrc 為 true 時才有效。

WebpackPartial

屬性

  • 區塊

    字串陣列 選用

    一或多個區塊名稱，其對應的輸出檔案應納入預先快取資訊清單。

  • 排除

    (string | RegExp | function)[] optional

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

  • excludeChunks

    字串陣列 選用

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

  • 包括

    (string | RegExp | function)[] optional

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

  • 模式

    字串 選填

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

方法

copyWorkboxLibraries()

workbox-build.copyWorkboxLibraries(
  destDirectory: string,
): Promise<string>

這會將 Workbox 使用的一組執行階段程式庫複製到本機目錄，並與 Service Worker 檔案一併部署。

除了部署這些本機副本，您也可以改用官方 CDN 網址中的 Workbox。

公開這個方法是為了讓使用 workbox-build.injectManifest 的開發人員受益，他們可能不想使用 Workbox 的 CDN 副本。使用 workbox-build.generateSW 的開發人員不需要明確呼叫這個方法。

參數

  • destDirectory

    字串

    新程式庫目錄的父項目錄路徑。

傳回

  • Promise<string>

    新建立的目錄名稱。

generateSW()

workbox-build.generateSW(
  config: GenerateSWOptions,
): Promise<BuildResult>

這個方法會根據您提供的選項，建立要預先快取的網址清單，也就是「預先快取資訊清單」。

此外，它也會採用其他選項來設定 Service Worker 的行為，例如應使用的任何 runtimeCaching 規則。

根據預先快取資訊清單和其他設定，這個外掛程式會在 swDest 將可供使用的 Service Worker 檔案寫入磁碟。

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, size, warnings} = await generateSW({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  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: ...,
  swDest: '...',
});

參數

傳回

getManifest()

workbox-build.getManifest(
  config: GetManifestOptions,
): Promise<GetManifestResult>

這個方法會根據您提供的選項，傳回要預先快取的網址清單 (稱為「預先快取資訊清單」)，以及項目數量和大小的詳細資料。

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, manifestEntries, size, warnings} = await getManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
});

參數

傳回

getModuleURL()

workbox-build.getModuleURL(
  moduleName: string,
  buildType: BuildType,
): string

參數

  • moduleName

    字串

  • buildType

    BuildType

傳回

  • 字串

injectManifest()

workbox-build.injectManifest(
  config: InjectManifestOptions,
): Promise<BuildResult>

這個方法會根據您提供的選項，建立要預先快取的網址清單，也就是「預先快取資訊清單」。

資訊清單會插入 swSrc 檔案，而預留位置字串 injectionPoint 則會決定資訊清單在檔案中的位置。

最終的 Service Worker 檔案 (已插入資訊清單) 會寫入磁碟的 swDest。

這個方法不會編譯或組合 swSrc 檔案，只會處理資訊清單的插入作業。

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, size, warnings} = await injectManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
  swDest: '...',
  swSrc: '...',
});

參數

傳回