Service Worker 設定檔

本主題說明 Service Worker 設定檔的各項屬性。

修改設定

ngsw-config.json 這個 JSON 設定檔，指定 Angular Service Worker 應該快取哪些檔案與資料 URL，以及應該如何更新已快取的檔案與資料。 Angular CLI 會在 ng build 期間處理這個設定檔。

所有檔案路徑都必須以 / 開頭，這對應到部署目錄——在 CLI 專案中通常是 dist/<project-name>。

除非另有註解，否則模式使用一種 limited* glob 格式，在內部會轉換成正規表示式：

模式範例：

Service Worker 設定屬性

以下各節說明設定檔的每一項屬性。

appData

這一節讓你可以傳入任何想傳的資料，用來描述應用程式的這個特定版本。 SwUpdate 服務會把該資料包含在更新通知中。 許多應用程式使用這一節提供額外資訊，用來顯示 UI 彈出視窗，通知使用者有可用更新。

index

指定作為索引頁面來滿足導覽請求的檔案。 通常是 /index.html。

assetGroups

_資產_是應用程式版本的一部分、會隨應用程式一起更新的資源。 它們可以包括從頁面來源載入的資源，以及從 CDN 與其他外部 URL 載入的第三方資源。 由於並非所有這類外部 URL 在建置時都已知，因此可以使用 URL 模式來進行符合比對。

這個欄位包含一個資產群組陣列，每個群組都定義一組資產資源，以及快取它們所依據的政策。

{
  "assetGroups": [
    {
      …
    },
    {
      …
    }
  ]
}

建議把較具體的資產群組放在清單較前面的位置。 例如，符合 /foo.js 的資產群組，應該出現在符合 *.js 的群組之前。

每個資產群組都同時指定一組資源，以及管理這些資源的政策。 這個政策決定資源何時被擷取，以及偵測到變更時會發生什麼事。

資產群組遵循這裡所示的 TypeScript 介面：

interface AssetGroup {
  name: string;
  installMode?: 'prefetch' | 'lazy';
  updateMode?: 'prefetch' | 'lazy';
  resources: {
    files?: string[];
    urls?: string[];
  };
  cacheQueryOptions?: {
    ignoreSearch?: boolean;
  };
}

每個 AssetGroup 由以下資產群組屬性定義。

name

name 是必填的。 它在設定的各版本之間識別這個特定的資產群組。

installMode

installMode 決定這些資源最初如何被快取。 installMode 可以是兩個值之一：

預設值為 prefetch。

updateMode

對於已經在快取中的資源，updateMode 決定在發現應用程式新版本時的快取行為。 群組中自前一版本以來已變更的任何資源，都會依 updateMode 來更新。

預設值為 installMode 所設定的值。

resources

這一節說明要快取的資源，細分如下列群組：

cacheQueryOptions

這些選項用來修改請求的比對行為。 它們會傳給瀏覽器的 Cache#match 函式。 詳情請參閱 MDN。 目前只支援以下選項：

dataGroups

與資產資源不同，資料請求不會隨應用程式一起版控。 它們會依手動設定的政策來快取，這類政策對 API 請求與其他資料相依性等情境更有用。

這個欄位包含一個資料群組陣列，每個群組都定義一組資料資源，以及快取它們所依據的政策。

{
  "dataGroups": [
    {
      …
    },
    {
      …
    }
  ]
}

建議把較具體的資料群組放在清單較前面的位置。 例如，符合 /api/foo.json 的資料群組，應該出現在符合 /api/*.json 的群組之前。

資料群組遵循這個 TypeScript 介面：

export interface DataGroup {
  name: string;
  urls: string[];
  version?: number;
  cacheConfig: {
    maxSize: number;
    maxAge: string;
    timeout?: string;
    refreshAhead?: string;
    strategy?: 'freshness' | 'performance';
  };
  cacheQueryOptions?: {
    ignoreSearch?: boolean;
  };
}

每個 DataGroup 由以下資料群組屬性定義。

name

與 assetGroups 類似，每個資料群組都有一個 name，用來唯一識別它。

urls

URL 模式的清單。 符合這些模式的 URL 會依這個資料群組的政策來快取。 只有非變更型的請求（GET 與 HEAD）會被快取。

• 不支援否定 glob 模式
• ? 會逐字比對；也就是說，它_只_符合 ? 字元

version

API 有時會以不向後相容的方式變更格式。 應用程式的新版本可能與舊的 API 格式不相容，因此也可能與來自該 API 的既有快取資源不相容。

version 提供一種機制，指出正在快取的資源已以不向後相容的方式更新，而舊的快取項目——也就是來自先前版本的項目——應該被捨棄。

version 是一個整數欄位，預設值為 1。

cacheConfig

以下屬性定義符合的請求被快取所依據的政策。

maxSize

快取中項目或回應的最大數量。

maxAge

maxAge 參數指出回應在被視為無效並清除之前，可以在快取中保留多久。maxAge 是一個持續時間字串，使用以下單位後綴：

例如，字串 3d12h 表示把內容快取最多三天半。

timeout

這個持續時間字串指定網路逾時。 網路逾時是指在設定如此做的情況下，Angular Service Worker 在改用已快取回應之前，等待網路回應的時間。 timeout 是一個持續時間字串，使用以下單位後綴：

例如，字串 5s30u 相當於五秒又 30 毫秒的網路逾時。

refreshAhead

這個持續時間字串指定在已快取資源到期之前的多久，Angular Service Worker 應該主動嘗試從網路重新整理該資源。 refreshAhead 持續時間是一個可選設定，決定 Service Worker 應該在已快取回應到期前多久，從網路發起請求來重新整理該資源。

例如，字串 1h30m 相當於到期時間前一小時又 30 分鐘。

strategy

Angular Service Worker 對資料資源可以使用兩種快取策略之一。

這基本上會執行以下動作：

1. 先嘗試從網路擷取。
2. 如果網路請求沒有立即完成，也就是在 0 ms 的逾時之後，忽略快取年齡並退回使用已快取的值。
3. 網路請求完成後，更新快取供未來請求使用。
4. 如果資源不存在於快取中，無論如何都等待網路請求。

cacheOpaqueResponses

Angular Service Worker 是否應該快取不透明回應。

如果未指定，預設值取決於資料群組所設定的策略：

cacheQueryOptions

詳情請參閱 assetGroups。

navigationUrls

這個可選的區段讓你可以指定一份自訂的 URL 清單，這些 URL 會重新導向到索引檔案。

處理導覽請求

ServiceWorker 會把不符合任何 asset 或 data 群組的導覽請求，重新導向到指定的索引檔案。 符合以下條件的請求會被視為導覽請求：

• 它的方法是 GET
• 它的模式是 navigate
• 依 Accept 標頭的值判斷，它接受 text/html 回應
• 它的 URL 符合以下條件：
  • URL 的最後一個路徑區段不能包含副檔名（也就是 .）
  • URL 不能包含 __

比對導覽請求 URL

雖然這些預設條件在大多數情況下都適用，但有時你會想設定不同的規則。 例如，你可能會想忽略特定的路由，例如不屬於 Angular 應用程式的路由，並把它們傳給伺服器。

這個欄位包含一個 URL 陣列，以及在執行階段比對的類 glob URL 模式。 它可以同時包含否定模式（也就是以 ! 開頭的模式）與非否定模式和 URL。

只有 URL 符合_任何_非否定 URL／模式、且_不_符合任何否定模式的請求，才會被視為導覽請求。 比對時會忽略 URL 查詢。

如果省略這個欄位，它的預設值為：

[
  '/**', // Include all URLs.
  '!/**/*.*', // Exclude URLs to files (containing a file extension in the last segment).
  '!/**/*__*', // Exclude URLs containing `__` in the last segment.
  '!/**/*__*/**', // Exclude URLs containing `__` in any other segment.
];

navigationRequestStrategy

這個可選屬性讓你可以設定 Service Worker 如何處理導覽請求：

{
  "navigationRequestStrategy": "freshness"
}

applicationMaxAge

這個可選屬性讓你可以設定 Service Worker 從快取提供某個應用程式版本多久。這個期限是從你建置應用程式的時間起算，而不是從檔案快取到裝置上的時間起算。

在 applicationMaxAge 之內，Service Worker 會從快取提供檔案。超過之後，Service Worker 會把所有請求都送往網路，包括資產與資料請求，即使沒有較新的版本也一樣。在部署新版建置、且裝置已取得它之前，應用程式無法離線運作。

若你省略 applicationMaxAge，就沒有限期上限，Service Worker 會提供快取的版本，不論它們有多舊。