Workbox-build

workbox-build 模組會整合至節點式建構程序，並可以產生整個 Service Worker，或產生可用來預先快取的資產清單，以供現有 Service Worker 使用。

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

要使用的模式

generateSW

generateSW 模式會為您建立 Service Worker 檔案，並透過設定選項進行自訂，然後將其寫入磁碟。

使用「generateSW」的時機

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

「不」使用 generateSW 的時機

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

injectManifest

injectManifest 模式會產生要預先快取的網址清單，然後將該預先快取資訊清單加入現有的 Service Worker 檔案。否則檔案會保持原樣。

使用「injectManifest」的時機

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

「不」使用 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 模式類似，但系統不會在來源 Service Worker 檔案中新增資訊清單，而是傳回資訊清單項目的陣列，以及項目數量和總大小的相關資訊。

您可以透過最常見的設定選項，在節點式建構指令碼中使用 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

    (字串 | ManifestEntry)[] 選用

    要友善載入的項目清單，以及系統在建構設定過程中產生的任何項目。

  • dontCacheBustURLsMatching

    規則運算式 選用

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

  • manifestTransforms

    ManifestTransform[] 選用

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

  • maximumFileSizeToCacheInBytes

    數字 選填

    預設值為 2097152

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

  • modifyURLPrefix

    物件選用

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

    使用範例：

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

BuildResult

類型

Omit<GetManifestResult"manifestEntries"
> & 物件

屬性

  • filePaths

    string[]

GeneratePartial

屬性

  • babelPresetEnvTargets

    string[] 選填

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

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

  • cacheId

    字串 選用

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

  • cleanupOutdatedCaches

    布林值 (選用)

    預設值為 false。

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

  • clientsClaim

    布林值 (選用)

    預設值為 false。

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

  • directoryIndex

    字串 選用

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

  • disableDevLogs

    布林值 (選用)

    預設值為 false。

  • ignoreURLParametersMatching

    RegExp[] 選填

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

  • importScripts

    string[] 選填

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

  • inlineWorkboxRuntime

    布林值 (選用)

    預設值為 false。

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

  • 模式

    字串 選用

    預設值為 "production"

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

  • 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 選用

    預設值為 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 檔案建立來源對應。

GenerateSWOptions

類型

BasePartial 和 GlobPartial & GeneratePartial 和 RequiredSWDestPartial 和 OptionalGlobDirectoryPartial

GetManifestOptions

類型

BasePartial 和 GlobPartial 和 RequiredGlobDirectoryPartial

GetManifestResult

屬性

  • 數量

    號碼

  • manifestEntries

    ManifestEntry[]

  • 大小

    號碼

  • 項警告

    string[]

GlobPartial

屬性

  • globFollow

    布林值 (選用)

    預設值為 true

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

  • globIgnores

    string[] 選填

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

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

  • globPatterns

    string[] 選填

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

    符合任一模式的檔案會包含在預先快取資訊清單中。詳情請參閱 glob 入門。

  • globStrict

    布林值 (選用)

    預設值為 true

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

  • templatedURLs

    物件選用

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

InjectManifestOptions

類型

BasePartial 和 GlobPartial 和 InjectPartial 和 RequiredSWDestPartial 和 RequiredGlobDirectoryPartial

InjectPartial

屬性

  • injectionPoint

    字串 選用

    預設值為 "self.__WB_MANIFEST"

    要在 swSrc 檔案中尋找的字串。找到之後，它就會由產生的友善快取資訊清單取代。

  • swSrc

    字串

    在建構程序期間，將讀取的 Service Worker 檔案路徑和檔案名稱 (相對於目前工作目錄)。

ManifestEntry

屬性

  • 完整性

    字串 選用

  • 修訂版本

    字串

  • 網址

    字串

ManifestTransform()

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

類型

功能

參數

  • manifestEntries

    (ManifestEntry 和物件)[]

    • 大小

      號碼

  • 編譯

    不明 (選用)

傳回

ManifestTransformResult

屬性

  • 資訊清單

    (ManifestEntry 和物件)[]

    • 大小

      號碼

  • 項警告

    string[] 選填

OptionalGlobDirectoryPartial

屬性

  • globDirectory

    字串 選用

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

RequiredGlobDirectoryPartial

屬性

  • globDirectory

    字串

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

RequiredSWDestPartial

屬性

  • swDest

    字串

    由建構程序建立的 Service Worker 檔案路徑和檔案名稱 (相對於目前工作目錄)。結尾必須是「.js」。

RuntimeCaching

屬性

StrategyName

列舉

"CacheFirst"

"CacheOnly"

WebpackGenerateSWOptions

類型

BasePartial 與 WebpackPartial 和 GeneratePartial 和 WebpackGenerateSWPartial

WebpackGenerateSWPartial

屬性

  • importScriptsViaChunks

    string[] 選填

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

  • swDest

    字串 選用

    預設值為 "service-worker.js"

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

WebpackInjectManifestOptions

類型

BasePartial 與 WebpackPartial 和 InjectPartial 和 WebpackInjectManifestPartial

WebpackInjectManifestPartial

屬性

  • compileSrc

    布林值 (選用)

    預設值為 true

    如果設為 true (預設值)，swSrc 檔案會由 Webpack 編譯。當 false 時，不會發生編譯作業 (且無法使用 webpackCompilationPlugins)。如果您想將資訊清單插入 (例如 JSON 檔案)，請設為 false。

  • swDest

    字串 選用

    將由這個外掛程式建立的 Service Worker 檔案資產名稱。如果省略，系統會根據 swSrc 名稱命名。

  • webpackCompilationPlugins

    any[] 選填

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

WebpackPartial

屬性

  • 區塊

    string[] 選填

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

  • 排除

    (字串 | RegExp | 函式)[] 選用

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

  • excludeChunks

    string[] 選填

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

  • 包括

    (字串 | RegExp | 函式)[] 選用

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

  • 模式

    字串 選用

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

方法

copyWorkboxLibraries()

workbox-build.copyWorkboxLibraries(
  destDirectory: string,
)

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

除了部署這些本機副本之外，您也可以從官方 CDN 網址使用 Workbox。

我們之所以提供這個方法，是因為開發人員使用 workbox-build.injectManifest 而不用擔心他們不想使用 Workbox 的 CDN 副本。使用 workbox-build.generateSW 的開發人員不需要明確呼叫此方法。

參數

  • destDirectory

    字串

    要建立程式庫的新目錄所在父項目錄路徑。

傳回

  • Promise<string>

    新建目錄的名稱。

generateSW()

workbox-build.generateSW(
  config: GenerateSWOptions,
)

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

還會採用其他選項來設定 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,
)

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

// 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 可決定資訊清單應位於檔案中的哪個位置。

資訊清單插入的最終 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: '...',
});

參數

傳回