填寫這份《一分鐘調查》,幫我們(開發組)做得更好!去填寫Home

Service Worker 配置

Service worker configuration

前提條件

Prerequisites

對下列知識有基本的瞭解:

A basic understanding of the following:


配置檔案 ngsw-config.json 指定了 Angular Service Worker 應該快取哪些檔案和資料的 URL,以及如何更新快取的檔案和資料。 Angular CLI 會在 ng build 期間處理配置檔案。 如果想手動處理,你可以使用 ngsw-config 工具(這裡的 <project-name> 就是要建構的專案名):

The ngsw-config.json configuration file specifies which files and data URLs the Angular service worker should cache and how it should update the cached files and data. The Angular CLI processes the configuration file during ng build. Manually, you can process it with the ngsw-config tool (where <project-name> is the name of the project being built):

      
      ./node_modules/.bin/ngsw-config ./dist/<project-name> ./ngsw-config.json [/base/href]
    

該配置檔案使用 JSON 格式。 所有檔案路徑都必須以 / 開頭,也就是相應的部署目錄 —— 在 CLI 專案中的它通常是 dist/<project-name>

The configuration file uses the JSON format. All file paths must begin with /, which corresponds to the deployment directory—usually dist/<project-name> in CLI projects.

如無特別說明,這些模式都使用受限的 glob 格式:

Unless otherwise noted, patterns use a limited glob format:

  • ** 匹配 0 到多段路徑。

    ** matches 0 or more path segments.

  • * 匹配 0 個或更多個除 / 之外的字元。

    * matches 0 or more characters excluding /.

  • ? 匹配除 / 之外的一個字元。

    ? matches exactly one character excluding /.

  • ! 字首表示該模式是反的,也就是說只包含與該模式不匹配的檔案。

    The ! prefix marks the pattern as being negative, meaning that only files that don't match the pattern will be included.

範例模式:

Example patterns:

  • /**/*.html 指定所有 HTML 檔案。

    /**/*.html specifies all HTML files.

  • /*.html 僅指定根目錄下的 HTML 檔案。

    /*.html specifies only HTML files in the root.

  • !/**/*.map 排除了所有原始碼對映檔案。

    !/**/*.map exclude all sourcemaps.

下面講講配置檔案中的每一節。

Each section of the configuration file is described below.

appData

本節允許你傳遞用來描述這個特定應用版本的任何資料。 SwUpdate 服務會在更新通知中包含這些資料。 許多應用會使用本節來提供 UI 彈窗時要顯示的附加資訊,以通知使用者有可用的更新。

This section enables you to pass any data you want that describes this particular version of the application. The SwUpdate service includes that data in the update notifications. Many applications use this section to provide additional information for the display of UI popups, notifying users of the available update.

index

指定用來充當索引頁的檔案以滿足導航請求。通常是 /index.html

Specifies the file that serves as the index page to satisfy navigation requests. Usually this is /index.html.

assetGroups

資產(Assets)是與應用一起更新的應用版本的一部分。 它們可以包含從頁面的同源地址載入的資源以及從 CDN 和其它外部 URL 載入的第三方資源。 由於在建構時可能沒法提前知道所有這些外部 URL,因此也可以指定 URL 的模式。

Assets are resources that are part of the application version that update along with the application. They can include resources loaded from the page's origin as well as third-party resources loaded from CDNs and other external URLs. As not all such external URLs may be known at build time, URL patterns can be matched.

該欄位包含一個資產組的陣列,每個資產組中會定義一組資產資源和它們的快取策略。

This field contains an array of asset groups, each of which defines a set of asset resources and the policy by which they are cached.

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

當 ServiceWorker 處理請求時,它將按照資源組在 ngsw-config.json 中出現的順序對其進行檢查。與所請求的資源匹配的第一個資源組將處理該請求。

When the ServiceWorker handles a request, it checks asset groups in the order in which they appear in ngsw-config.json. The first asset group that matches the requested resource handles the request.

建議將更具體的資源組放在列表中較高的位置。比如,與 /foo.js 匹配的資源組應出現在與 *.js 匹配的資源組之前。

It is recommended that you put the more specific asset groups higher in the list. For example, an asset group that matches /foo.js should appear before one that matches *.js.

每個資產組都會指定一組資源和一個管理它們的策略。 此策略用來決定何時獲取資源以及當檢測到更改時該怎麼做。

Each asset group specifies both a group of resources and a policy that governs them. This policy determines when the resources are fetched and what happens when changes are detected.

這些資產組會遵循下面的 Typescript 介面:

Asset groups follow the Typescript interface shown here:

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

name

name 是強制性的。它用來標識該配置檔案版本中這個特定的資產組。

A name is mandatory. It identifies this particular group of assets between versions of the configuration.

installMode

installMode 決定了這些資源最初的快取方式。installMode 可以取如下兩個值之一:

The installMode determines how these resources are initially cached. The installMode can be either of two values:

  • prefetch 告訴 Angular Service Worker 在快取當前版本的應用時要獲取每一個列出的資源。 這是個頻寬密集型的模式,但可以確保這些資源在請求時可用,即使瀏覽器正處於離線狀態。

    prefetch tells the Angular service worker to fetch every single listed resource while it's caching the current version of the application. This is bandwidth-intensive but ensures resources are available whenever they're requested, even if the browser is currently offline.

  • lazy 不會預先快取任何資源。相反,Angular Service Worker 只會快取它收到請求的資源。 這是一種按需快取模式。永遠不會請求的資源也永遠不會被快取。 這對於像為不同解析度提供的圖片之類別的資源很有用,那樣 Service Worker 就只會為特定的螢幕和裝置方向快取正確的資源。

    lazy does not cache any of the resources up front. Instead, the Angular service worker only caches resources for which it receives requests. This is an on-demand caching mode. Resources that are never requested will not be cached. This is useful for things like images at different resolutions, so the service worker only caches the correct assets for the particular screen and orientation.

預設為 prefetch

Defaults to prefetch.

updateMode

對於已經存在於快取中的資源,updateMode 會決定在發現了新版本應用後的快取行為。 自上一版本以來更改過的所有組中資源都會根據 updateMode 進行更新。

For resources already in the cache, the updateMode determines the caching behavior when a new version of the application is discovered. Any resources in the group that have changed since the previous version are updated in accordance with updateMode.

  • prefetch 會告訴 Service Worker 立即下載並快取更新過的資源。

    prefetch tells the service worker to download and cache the changed resources immediately.

  • lazy 告訴 Service Worker 不要快取這些資源,而是先把它們看作未被請求的,等到它們再次被請求時才進行更新。 lazy 這個 updateMode 只有在 installMode 也同樣是 lazy 時才有效。

    lazy tells the service worker to not cache those resources. Instead, it treats them as unrequested and waits until they're requested again before updating them. An updateMode of lazy is only valid if the installMode is also lazy.

其預設值為 installMode 的值。

Defaults to the value installMode is set to.

resources

本節描述要快取的資源,分為如下幾組:

This section describes the resources to cache, broken up into the following groups:

  • files 列出了與 dist 目錄中的檔案相匹配的模式。它們可以是單個檔案也可以是能匹配多個檔案的類似 glob 的模式。

    files lists patterns that match files in the distribution directory. These can be single files or glob-like patterns that match a number of files.

  • urls 包括要在執行時進行匹配的 URL 和 URL 模式。 這些資源不是直接獲取的,也沒有內容雜湊,但它們會根據 HTTP 標頭進行快取。 這對於像 Google Fonts 服務這樣的 CDN 非常有用。
    (不支援 glob 的逆模式,? 將會按字面匹配;也就是說它不會匹配除了 ? 之外的任何字元。)

    urls includes both URLs and URL patterns that will be matched at runtime. These resources are not fetched directly and do not have content hashes, but they will be cached according to their HTTP headers. This is most useful for CDNs such as the Google Fonts service.
    (Negative glob patterns are not supported and ? will be matched literally; that is, it will not match any character other than ?.)

cacheQueryOptions

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

These options are used to modify the matching behavior of requests. They are passed to the browsers Cache#match function. See MDN for details. Currently, only the following options are supported:

  • ignoreSearch: 忽略查詢引數。預設為 false

    ignoreSearch: Ignore query parameters. Defaults to false.

dataGroups

與這些資產性(asset)資源不同,資料請求不會隨應用一起版本化。 它們會根據手動配置的策略進行快取,這些策略對 API 請求和所依賴的其它資料等情況會更有用。

Unlike asset resources, data requests are not versioned along with the application. They're cached according to manually-configured policies that are more useful for situations such as API requests and other data dependencies.

本欄位包含一個數據組的陣列,其中的每一個條目都定義了一組資料資源以及對它們的快取策略。

This field contains an array of data groups, each of which defines a set of data resources and the policy by which they are cached.

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

當 ServiceWorker 處理請求時,它將按照資料組在 ngsw-config.json 中出現的順序對其進行檢查。與所請求的資源匹配的第一個資料組將處理該請求。

When the ServiceWorker handles a request, it checks data groups in the order in which they appear in ngsw-config.json. The first data group that matches the requested resource handles the request.

建議將更具體的資料組放在列表中較高的位置。比如,與 /api/foo.json 匹配的資料組應出現在與 /api/*.json 匹配的資料組之前。

It is recommended that you put the more specific data groups higher in the list. For example, a data group that matches /api/foo.json should appear before one that matches /api/*.json.

資料組遵循下列 TypeScript 介面:

Data groups follow this Typescript interface:

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

name

assetGroups 下類似,每個資料組也都有一個 name,用作它的唯一標識。

Similar to assetGroups, every data group has a name which uniquely identifies it.

urls

一個 URL 模式的列表。匹配這些模式的 URL 將會根據該資料組的策略進行快取。只有非修改型的請求(GET 和 HEAD)才會進行快取。

A list of URL patterns. URLs that match these patterns are cached according to this data group's policy. Only non-mutating requests (GET and HEAD) are cached.

  • (不支援 glob 中的否定模式)。

    Negative glob patterns are not supported.

  • ? 只做字面匹配,也就是說,它能匹配 ? 字元。

    ? is matched literally; that is, it matches only the character ?.

version

API 有時可能會以不向後相容的方式更改格式。 新版本的應用可能與舊的 API 格式不相容,因此也就與該 API 中目前已快取的資源不相容。

Occasionally APIs change formats in a way that is not backward-compatible. A new version of the application may not be compatible with the old API format and thus may not be compatible with existing cached resources from that API.

version 提供了一種機制,用於指出這些被快取的資源已經透過不向後相容的方式進行了更新,並且舊的快取條目(即來自以前版本的快取條目)應該被丟棄。

version provides a mechanism to indicate that the resources being cached have been updated in a backwards-incompatible way, and that the old cache entries—those from previous versions—should be discarded.

version 是個整型欄位,預設為 0

version is an integer field and defaults to 1.

cacheConfig

本節定義了對匹配上的請求進行快取時的策略。

This section defines the policy by which matching requests will be cached.

maxSize

(必需)快取的最大條目數或響應數。開放式快取可以無限增長,並最終超過儲存配額,建議適時清理。

(required) The maximum number of entries, or responses, in the cache. Open-ended caches can grow in unbounded ways and eventually exceed storage quotas, calling for eviction.

maxAge

(必需)maxAge 引數表示在響應因失效而要清除之前允許在快取中留存的時間。maxAge 是一個表示持續時間的字串,可使用以下單位作為字尾:

(required) The maxAge parameter indicates how long responses are allowed to remain in the cache before being considered invalid and evicted. maxAge is a duration string, using the following unit suffixes:

  • d:天數

    d: days

  • h:小時數

    h: hours

  • m:分鐘數

    m: minutes

  • s:秒數

    s: seconds

  • u:微秒數

    u: milliseconds

比如,字串 3d12h 規定此內容最多快取三天半。

For example, the string 3d12h will cache content for up to three and a half days.

timeout

這個表示持續時間的字串用於指定網路超時時間。 如果配置了網路超時時間,Angular Service Worker 就會先等待這麼長時間再使用快取。timeout 是一個表示持續時間的字串,使用下列字尾單位:

This duration string specifies the network timeout. The network timeout is how long the Angular service worker will wait for the network to respond before using a cached response, if configured to do so. timeout is a duration string, using the following unit suffixes:

  • d:天

    d: days

  • h:小時

    h: hours

  • m:分鐘

    m: minutes

  • s:秒

    s: seconds

  • u:毫秒

    u: milliseconds

比如,字串 5s30u 將會被翻譯成 5 秒零 30 毫秒的網路超時。

For example, the string 5s30u will translate to five seconds and 30 milliseconds of network timeout.

strategy

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

The Angular service worker can use either of two caching strategies for data resources.

  • performance,預設值,為儘快給出響應而優化。如果快取中存在某個資源,則使用這個快取版本,而不再發起網路請求。 它允許資源有一定的陳舊性(取決於 maxAge)以換取更好的效能。適用於那些不經常改變的資源,例如使用者頭像。

    performance, the default, optimizes for responses that are as fast as possible. If a resource exists in the cache, the cached version is used, and no network request is made. This allows for some staleness, depending on the maxAge, in exchange for better performance. This is suitable for resources that don't change often; for example, user avatar images.

  • freshness 為資料的即時性而優化,優先從網路獲取請求的資料。只有當網路超時時,請求才會根據 timeout 的設定回退到快取中。這對於那些頻繁變化的資源很有用,例如賬戶餘額。

    freshness optimizes for currency of data, preferentially fetching requested data from the network. Only if the network times out, according to timeout, does the request fall back to the cache. This is useful for resources that change frequently; for example, account balances.

你還可以模擬第三種策略 staleWhileRevalidate,它會返回快取的資料(如果可用),但是也會在後臺從網路上獲取新資料,以供下次使用。 要使用本策略,請在 cacheConfig 中把 strategy 設定為 freshness,並且把 timeout 設定為 0u

You can also emulate a third strategy, staleWhileRevalidate, which returns cached data (if available), but also fetches fresh data from the network in the background for next time. To use this strategy set strategy to freshness and timeout to 0u in cacheConfig.

本質上說,它會做如下工作:

This will essentially do the following:

  1. 首先嚐試從網路上獲取。

    Try to fetch from the network first.

  2. 如果網路請求沒有在 0ms 內(也就是立刻)完成,就用快取做為後備(忽略快取有效期)。

    If the network request does not complete after 0ms (that is, immediately), fall back to the cache (ignoring cache age).

  3. 一旦網路請求完成,就更新快取,以供將來的請求使用。

    Once the network request completes, update the cache for future requests.

  4. 如果指定的資源在快取中不存在,總是等待網路請求。

    If the resource does not exist in the cache, wait for the network request anyway.

cacheQueryOptions

詳情參閱 assetGroups

See assetGroups for details.

這個可選節讓你可以指定一個自訂的 URL 列表,它們都會被重新導向到索引檔案。

This optional section enables you to specify a custom list of URLs that will be redirected to the index file.

處理導航請求

Handling navigation requests

對於沒有匹配上任何 assetdata 組的導航請求,ServiceWorker 會把它們重新導向到指定的索引檔案。下列請求將會視為導航請求:

The ServiceWorker will redirect navigation requests that don't match any asset or data group to the specified index file. A request is considered to be a navigation request if:

  1. 它的模式navigation

    Its mode is navigation.

  2. 它接受 text/html 響應(根據 Accept 頭的值決定)。

    It accepts a text/html response (as determined by the value of the Accept header).

  3. 它的 URL 符合特定的條件(稍後講)。

    Its URL matches certain criteria (see below).

預設情況下,這些條件是:

By default, these criteria are:

  1. URL 的最後一段路徑中不能包含副檔名(比如 .)。

    The URL must not contain a file extension (that is, a .) in the last path segment.

  2. URL 中不能包含 __

    The URL must not contain __.

要配置瀏覽請求是否傳送到網路,請參閱 navigationRequestStrategy 部分。

To configure whether navigation requests are sent through to the network or not, see the navigationRequestStrategy section.

匹配導航請求的 URL

Matching navigation request URLs

雖然這些預設條件在大多數情況下都挺好用,不過有時還是要配置一些不同的規則。比如,你可能希望忽略一些特定的路由(它們可能不是 Angular 應用的一部分),而是把它們透傳給伺服器。

While these default criteria are fine in most cases, it is sometimes desirable to configure different rules. For example, you may want to ignore specific routes (that are not part of the Angular app) and pass them through to the server.

該欄位包含一個將要在執行期間匹配的 URL 和 類似 glob 的 URL 模式。 它既可以包含正向模式也可以包含反向模式(比如用 ! 開頭的模式)。

This field contains an array of URLs and glob-like URL patterns that will be matched at runtime. It can contain both negative patterns (that is, patterns starting with !) and non-negative patterns and URLs.

只有那些能匹配任意正向 URL 或 URL 模式並且不匹配任何一個反向模式的 URL 才會視為導航請求。當匹配時,這些 URL 查詢將會被忽略。

Only requests whose URLs match any of the non-negative URLs/patterns and none of the negative ones will be considered navigation requests. The URL query will be ignored when matching.

如果省略了該欄位,它的預設值是:

If the field is omitted, it defaults to:

      
      [
  '/**',           // Include all URLs.
  '!/**/*.*',      // Exclude URLs to files.
  '!/**/*__*',     // Exclude URLs containing `__` in the last segment.
  '!/**/*__*/**',  // Exclude URLs containing `__` in any other segment.
]
    

透過此可選屬性,你可以配置服務工作者如何處理導航請求:

This optional property enables you to configure how the service worker handles navigation requests:

      
      {
  "navigationRequestStrategy": "freshness"
}
    

可能的值:

Possible values:

  • 'performance':預設設定。提供指定的索引檔案,它通常會被快取。

    'performance': The default setting. Serves the specified index file, which is typically cached.

  • 'freshness':將請求透傳到網路,並在離線時回退到 performance 模式。當伺服器在用 HTTP 重新導向(3xx 狀態程式碼)將導航請求重新導向到其他位置時,此值很有用。使用此值的原因包括:

    'freshness': Passes the requests through to the network and falls back to the performance behavior when offline. This value is useful when the server redirects the navigation requests elsewhere using an HTTP redirect (3xx status code). Reasons for using this value include:

    • 當應用尚未處理身份驗證時,重新導向到身份驗證網站。

      Redirecting to an authentication website when authentication is not handled by the application.

    • 重新導向特定的 URL,以免在網站重新設計後破壞現有的連結/書籤。

      Redirecting specific URLs to avoid breaking existing links/bookmarks after a website redesign.

    • 當頁面暫時關閉時,重新導向到其他網站,例如伺服器狀態頁。

      Redirecting to a different website, such as a server-status page, while a page is temporarily down.

freshness 策略通常會導致向伺服器傳送更多請求,這可能會增加響應延遲。建議你儘可能使用預設的效能策略。

The freshness strategy usually results in more requests sent to the server, which can increase response latency. It is recommended that you use the default performance strategy whenever possible.