Service Worker 配置

前提条件

对下列知识有基本的了解：

• 生产环境下的 Service Worker。

---

配置文件 src/ngsw-config.json 指定了 Angular Service Worker 应该缓存哪些文件和数据的 URL，以及如何更新缓存的文件和数据。 CLI 会在 ng build --prod 期间处理配置文件。 如果想手动处理，你可以使用 ngsw-config 工具：

content_copyngsw-config dist src/ngsw-config.json /base/href

该配置文件使用 JSON 格式。 所有文件路径都必须以 / 开头，也就是部署目录 —— 在 CLI 项目中的它通常是 dist。

如无特别说明，这些模式都使用受限的 glob 格式：

• ** 匹配 0 到多段路径。
• * 匹配 0 个或更多个除 / 之外的字符。
• ? 匹配除 / 之外的一个字符。
• ! 前缀表示该模式是反的，也就是说只包含与该模式不匹配的文件。

范例模式：

• /**/*.html 指定所有 HTML 文件。
• /*.html 仅指定根目录下的 HTML 文件。
• !/**/*.map 排除了所有源码映射文件。

下面讲讲配置文件中的每一节。

appData

本节允许你传递用来描述这个特定应用版本的任何数据。 SwUpdate 服务会在更新通知中包含这些数据。 许多应用会使用本节来提供 UI 弹窗时要显示的附加信息，以通知用户有可用的更新。

index

指定用来充当索引页的文件以满足导航请求。通常是/index.html。

assetGroups

资产（Assets）是与应用一起更新的应用版本的一部分。 它们可以包含从页面的同源地址加载的资源以及从 CDN 和其它外部 URL 加载的第三方资源。 由于在构建时可能没法提前知道所有这些外部 URL，因此也可以指定 URL 的模式。

该字段包含一个资产组的数组，每个资产组中会定义一组资产资源和它们的缓存策略。

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

每个资产组都会指定一组资源和一个管理它们的策略。 此策略用来决定何时获取资源以及当检测到更改时该怎么做。

这些资产组会遵循下面的 Typescript 接口：

content_copyinterface AssetGroup {
  name: string;
  installMode?: 'prefetch' | 'lazy';
  updateMode?: 'prefetch' | 'lazy';
  resources: {
    files?: string[];
    /** @deprecated As of v6 `versionedFiles` and `files` options have the same behavior. Use `files` instead. */
    versionedFiles?: string[];
    urls?: string[];
  };
}

name

name 是强制性的。它用来标识该配置文件版本中这个特定的资产组。

installMode

installMode 决定了这些资源最初的缓存方式。installMode 可以取如下两个值之一：

• prefetch 告诉 Angular Service Worker 在缓存当前版本的应用时要获取每一个列出的资源。 这是个带宽密集型的模式，但可以确保这些资源在请求时可用，即使浏览器正处于离线状态。
• lazy 不会预先缓存任何资源。相反，Angular Service Worker 只会缓存它收到请求的资源。 这是一种按需缓存模式。永远不会请求的资源也永远不会被缓存。 这对于像为不同分辨率提供的图片之类的资源很有用，那样 Service Worker 就只会为特定的屏幕和设备方向缓存正确的资源。

updateMode

对于已经存在于缓存中的资源，updateMode 会决定在发现了新版本应用后的缓存行为。 自上一版本以来更改过的所有组中资源都会根据 updateMode 进行更新。

• prefetch 会告诉 Service Worker 立即下载并缓存更新过的资源。
• lazy 告诉 Service Worker 不要缓存这些资源，而是先把它们看作未被请求的，等到它们再次被请求时才进行更新。 lazy 这个 updateMode 只有在 installMode 也同样是 lazy 时才有效。

resources

本节描述要缓存的资源，分为三组。

• files 列出了与 dist 目录中的文件相匹配的模式。它们可以是单个文件也可以是能匹配多个文件的类似 glob 的模式。
• versionedFiles 和 files 相似，但是它用来对工件进行构建，这些工件已经在文件名中包含了一个散列，用于让其缓存失效。 如果 Angular Service Worker 能假定这些文件在文件名不变时其内容也不会变，那它就可以从某些方面优化这种操作。
• urls 包括要在运行时进行匹配的 URL 和 URL 模式。 这些资源不是直接获取的，也没有内容散列，但它们会根据 HTTP 标头进行缓存。 这对于像 Google Fonts 服务这样的 CDN 非常有用。 （不支持 glob 的逆模式）

dataGroups

与这些资产性（asset）资源不同，数据请求不会随应用一起版本化。 它们会根据手动配置的策略进行缓存，这些策略对 API 请求和所依赖的其它数据等情况会更有用。

数据组遵循下列 TypeScript 接口：

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

name

和 assetGroups 下类似，每个数据组也都有一个 name ，用作它的唯一标识。

urls

一个 URL 模式的列表。匹配这些模式的 URL 将会根据该数据组的策略进行缓存。 （不支持 glob 中的逆模式）

version

API 有时可能会以不向后兼容的方式更改格式。 新版本的应用可能与旧的 API 格式不兼容，因此也就与该 API 中目前已缓存的资源不兼容。

version 提供了一种机制，用于指出这些被缓存的资源已经通过不向后兼容的方式进行了更新，并且旧的缓存条目（即来自以前版本的缓存条目）应该被丢弃。

version 是个整型字段，默认为 0。

cacheConfig

本节定义了对匹配上的请求进行缓存时的策略。

maxSize

（必需）缓存的最大条目数或响应数。开放式缓存可以无限增长，并最终超过存储配额，建议适时清理。

maxAge

（必需）maxAge 参数表示在响应因失效而要清除之前允许在缓存中留存的时间。maxAge 是一个表示持续时间的字符串，可使用以下单位作为后缀：

• d：天数
• h：小时数
• m：分钟数
• s：秒数
• u：微秒数

比如，字符串 3d12h 规定此内容最多缓存三天半。

timeout

这个表示持续时间的字符串用于指定网络超时时间。 如果配置了它，Angular Service Worker 在开始使用缓存之前就会先等待网络给出响应，这个等待时间就是网络超时时间。

strategy

Angular Service Worker 可以使用两种缓存策略之一来获取数据资源。

• performance，默认值，为尽快给出响应而优化。如果缓存中存在某个资源，则使用这个缓存版本。 它允许资源有一定的陈旧性（取决于 maxAge）以换取更好的性能。适用于那些不经常改变的资源，例如用户头像。
• freshness 为数据的即时性而优化，优先从网络获取请求的数据。只有当网络超时时，请求才会根据 timeout 的设置回退到缓存中。这对于那些频繁变化的资源很有用，例如账户余额。

navigationUrls

这个可选节让你可以指定一个自定义的 URL 列表，它们都会被重定向到索引文件。

处理导航请求

对于没有匹配上任何 asset 或 data 组的导航请求，ServiceWorker 会把它们重定向到指定的索引文件。下列请求将会视为导航请求：

1. 它的模式是 navigation。
2. 它接受 text/html 响应（根据 Accept 头的值决定）。
3. 它的 URL 符合特定的条件（稍后讲）。

默认情况下，这些条件是：

1. URL 的最后一段路径中不能包含文件扩展名（比如 .）。
2. URL 中不能包含 __。

匹配导航请求的 URL

虽然这些默认条件在大多数情况下都挺好用，不过有时还是要配置一些不同的规则。比如，你可能希望忽略一些特定的路由（它们可能不是 Angular 应用的一部分），而是把它们透传给服务器。

该字段包含一个将要在运行期间匹配的 URL 和 类似 glob 的 URL模式。 它既可以包含正向模式也可以包含反向模式（比如用 ! 开头的模式）。

只有那些能匹配任意正向 URL 或 URL 模式并且不匹配任何一个反向模式的 URL 才会视为导航请求。当匹配时，这些 URL 查询将会被忽略。

如果省略了该字段，它的默认值是：

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