Workbox-build

workbox-build 模組會整合至以節點為基礎的建構程序，並可產生整個服務工作程，或只產生可用於現有服務工作程的預先快取資產清單。

大多數開發人員會使用 generateSW 和 injectManifest 這兩種模式。下列問題的答案可協助您選擇正確的模式和設定。

要使用的模式

generateSW

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

使用 generateSW 的時機

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

不應使用 generateSW 的情況

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

injectManifest

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

使用 injectManifest 的時機

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

不應使用 injectManifest 的情況

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

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.`);
});

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

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

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.`);
});

系統會根據設定檔挑選的檔案建立預先快取資訊清單，並將其插入現有的服務工作者檔案。

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

其他模式

我們認為 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

    RegExp 選填

    系統會假設符合此條件的資產透過其網址擁有專屬版本，並免除在填入預快取時執行的一般 HTTP 快取破壞作業。雖然不是必要，但如果您現有的建構程序已在每個檔案名稱中插入 [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

    string[] 選填

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

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

  • cacheId

    string 選填

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

  • cleanupOutdatedCaches

    boolean 選填

    預設值：false

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

  • clientsClaim

    boolean 選填

    預設值：false

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

  • directoryIndex

    string 選填

    如果結尾為 / 的網址導覽要求無法與預快取網址相符，系統會將這個值附加到網址，並檢查是否有預快取相符項目。這項屬性應設為網路伺服器用於目錄索引的值。

  • disableDevLogs

    boolean 選填

    預設值：false

  • ignoreURLParametersMatching

    RegExp[] 選填

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

  • importScripts

    string[] 選填

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

  • inlineWorkboxRuntime

    boolean 選填

    預設值：false

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

  • 模式

    string 選填

    預設值："production"

    如果設為「production」，系統會產生經過最佳化的服務工作者套件，其中會排除偵錯資訊。如果未在此處明確設定，系統會使用 process.env.NODE_ENV 值，如果失敗，則會改用 'production'。

  • navigateFallback

    string 選填

    預設值：null

    如果指定，則所有未預先快取的網址導覽要求，都會使用提供的網址中的 HTML 來滿足要求。您必須傳入預先快取資訊清單中列出的 HTML 文件網址。這項功能適用於單頁應用程式情境，也就是您希望所有導覽都使用通用 App Shell HTML 的情況。

  • navigateFallbackAllowlist

    RegExp[] 選填

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

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

  • navigateFallbackDenylist

    RegExp[] 選填

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

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

  • navigationPreload

    boolean 選填

    預設值：false

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

  • offlineGoogleAnalytics

    boolean | GoogleAnalyticsInitializeOptions 選用

    預設值：false

    控制是否納入 離線 Google Analytics 支援功能。當 true 時，對 workbox-google-analytics 的 initialize() 呼叫會新增至產生的服務工作者。將其設為 Object 時，系統會將該物件傳遞至 initialize() 呼叫，讓您自訂行為。

  • runtimeCaching

    RuntimeCaching[] 選用

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

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

  • skipWaiting

    boolean 選填

    預設值：false

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

  • sourcemap

    boolean 選填

    預設值：true

    是否要為產生的服務工作者檔案建立來源圖。

GenerateSWOptions

類型

BasePartial & GlobPartial & GeneratePartial & RequiredSWDestPartial & OptionalGlobDirectoryPartial

GetManifestOptions

類型

BasePartial & GlobPartial & RequiredGlobDirectoryPartial

GetManifestResult

屬性

  • 數量

    數字

  • manifestEntries

    ManifestEntry[]

  • 大小

    數字

  • 項警告

    string[]

GlobPartial

屬性

  • globFollow

    boolean 選填

    預設值：true

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

  • globIgnores

    string[] 選填

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

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

  • globPatterns

    string[] 選填

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

    符合任一模式的檔案都會納入預快取資訊清單。詳情請參閱 glob 入門說明。

  • globStrict

    boolean 選填

    預設值：true

    如果為 true，產生預快取資訊清單時讀取目錄的錯誤會導致建構失敗。如果設為 False，系統會略過有問題的目錄。詳情請參閱 glob 說明文件中的 strict 定義。

  • templatedURLs

    物件 選填

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

InjectManifestOptions

類型

BasePartial & GlobPartial & InjectPartial & RequiredSWDestPartial & RequiredGlobDirectoryPartial

InjectPartial

屬性

  • injectionPoint

    string 選填

    預設值："self.__WB_MANIFEST"

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

  • swSrc

    字串

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

ManifestEntry

屬性

  • 完整性

    string 選填

  • 修訂

    字串

  • 網址

    字串

ManifestTransform()

workbox-build.ManifestTransform(
  manifestEntries: (ManifestEntry & object)[],
  compilation?: unknown,
)

類型

函式

參數

  • manifestEntries

    (ManifestEntry & object)[]

    • 大小

      數字

  • 編譯

    unknown 選填

傳回

ManifestTransformResult

屬性

  • 資訊清單

    (ManifestEntry & object)[]

    • 大小

      數字

  • 項警告

    string[] 選填

OptionalGlobDirectoryPartial

屬性

  • globDirectory

    string 選填

    您要比對 globPatterns 的本機目錄。這是以目前目錄為基準的相對路徑。

RequiredGlobDirectoryPartial

屬性

  • globDirectory

    字串

    您要比對 globPatterns 的本機目錄。這是以目前目錄為基準的相對路徑。

RequiredSWDestPartial

屬性

  • swDest

    字串

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

RuntimeCaching

屬性

StrategyName

列舉

"CacheFirst"

"CacheOnly"

「NetworkFirst」

"NetworkOnly"

"StaleWhileRevalidate"

WebpackGenerateSWOptions

類型

BasePartial & WebpackPartial & GeneratePartial & WebpackGenerateSWPartial

WebpackGenerateSWPartial

屬性

  • importScriptsViaChunks

    string[] 選填

    一或多個 Webpack 區塊名稱。這些區塊的內容會透過 importScripts() 的呼叫，納入產生的服務工作者。

  • swDest

    string 選填

    預設值："service-worker.js"

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

WebpackInjectManifestOptions

類型

BasePartial & WebpackPartial & InjectPartial & WebpackInjectManifestPartial

WebpackInjectManifestPartial

屬性

  • compileSrc

    boolean 選填

    預設值：true

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

  • swDest

    string 選填

    這個外掛程式將建立的服務工作者檔案的素材資源名稱。如果省略，名稱會根據 swSrc 名稱。

  • webpackCompilationPlugins

    any[] 選填

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

WebpackPartial

屬性

  • 區塊

    string[] 選填

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

  • 排除

    (string | RegExp | function)[] 選填

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

  • excludeChunks

    string[] 選填

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

  • 包含

    (string | RegExp | function)[] 選填

    用於在預快取資訊清單中加入資產的一或多個指定項目。這會按照 webpack 的標準 include 選項遵循相同規則進行解讀。

  • 模式

    string 選填

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

方法

copyWorkboxLibraries()

workbox-build.copyWorkboxLibraries(
  destDirectory: string,
)

這會將 Workbox 使用的一組執行階段程式庫複製到本機目錄，該目錄應與服務工作站檔案一併部署。

您可以改為從 Workbox 的官方 CDN 網址使用 Workbox，而非部署這些本機副本。

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

參數

  • destDirectory

    字串

    父項目錄的路徑，系統會在該目錄下建立新的程式庫目錄。

傳回

  • Promise<string>

    新建立的目錄名稱。

generateSW()

workbox-build.generateSW(
  config: GenerateSWOptions,
)

這個方法會根據您提供的選項，建立要預快取的網址清單 (稱為「預快取資訊清單」)。

它也會採用其他選項，設定服務工作者的行為，例如應使用的任何 runtimeCaching 規則。

根據預先快取資訊清單和其他設定，將可立即使用的服務工作站檔案寫入 swDest 磁碟。

// 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,
)

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

// 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,
)

參數

  • moduleName

    字串

  • buildType

    BuildType

傳回

  • 字串

injectManifest()

workbox-build.injectManifest(
  config: InjectManifestOptions,
)

這個方法會根據您提供的選項，建立要預快取的網址清單 (稱為「預快取資訊清單」)。

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

最終服務工作者檔案 (已插入資訊清單) 會寫入 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: '...',
});

參數

傳回