Service Worker 快速起步link

Getting started with service workerslink

本文档解释了如何在 Angular CLI 项目中启用对 Angular Service Worker 的支持。稍后它会用一个简单的范例来向你展示 Service Worker 实践，包括加载和基础的缓存功能。

This document explains how to enable Angular service worker support in projects that you created with the Angular CLI. It then uses a simple example to show you a service worker in action, demonstrating loading and basic caching.

前提条件link

Prerequisiteslink

对 Angular Service Worker 简介中的信息有了基本的了解。

A basic understanding of the information in Introduction to Angular service workers.

为你的项目添加 Service Workerlink

Adding a service worker to your projectlink

要让你的项目支持 Angular Service Worker，可以使用 CLI 命令 ng add @angular/pwa。它会添加 service-worker 包，并建立必要的支持文件，小心翼翼地配置你的应用，以便使用 Service Worker。

To set up the Angular service worker in your project, use the CLI command ng add @angular/pwa. It takes care of configuring your app to use service workers by adding the service-worker package along with setting up the necessary support files.

      
        content_copy
      
      ng add @angular/pwa --project *project-name*
    

上述命令完成了如下步骤：

The above command completes the following actions:

1. 把 @angular/service-worker 添加到你的项目中。

   Adds the @angular/service-worker package to your project.

2. 在 CLI 中启用 Service Worker 的构建支持。

   Enables service worker build support in the CLI.

3. 在应用模块中导入并注册 Service Worker。

   Imports and registers the service worker in the app module.

4. 修改 index.html 文件：

   Updates the index.html file:

   • 包含要添加到 manifest.json 文件中的链接。

     Includes a link to add the manifest.json file.

   • 为 theme-color 添加 meta 标签。

     Adds meta tags for theme-color.

5. 创建图标文件，以支持安装渐进式应用（PWA）。

   Installs icon files to support the installed Progressive Web App (PWA).

6. 创建一个名叫 ngsw-config.json的 Service Worker 配置文件，它会用来指定缓存的行为以及其它设定。

   Creates the service worker configuration file called ngsw-config.json, which specifies the caching behaviors and other settings.

现在，构建本项目：

Now, build the project:

      
        content_copy
      
      ng build --prod
    

现在，这个 CLI 项目就可以使用 Angular Service Worker 了。

The CLI project is now set up to use the Angular service worker.

Service Worker 实战：向导link

Service worker in action: a tourlink

本节用一个范例应用来演示一下 Service Worker 实战。

This section demonstrates a service worker in action, using an example application.

用 http-server 启动开发服务器link

Serving with http-serverlink

由于 ng serve 对 Service Worker 无效，所以必须用一个独立的 HTTP 服务器在本地测试你的项目。 你可以使用任何 HTTP 服务器。下面这个例子使用来自 npm 中的 http-server 包。 为了减小端口冲突的可能性，我们在一个专用端口上进行测试。

Because ng serve does not work with service workers, you must use a separate HTTP server to test your project locally. You can use any HTTP server. The example below uses the http-server package from npm. To reduce the possibility of conflicts and avoid serving stale content, test on a dedicated port and disable caching.

要想使用 http-server 在包含这些 web 文件的目录上启动服务，运行下列命令：

To serve the directory containing your web files with http-server, run the following command:

      
        content_copy
      
      http-server -p 8080 -c-1 dist/<project-name>
    

最初的加载link

Initial loadlink

在服务器运行起来之后，你可以在浏览器中访问 http://localhost:8080/。你的应用像通常一样加载。

With the server running, you can point your browser at http://localhost:8080/. Your application should load normally.

提示： 当测试 Angular Service Worker 时，最好使用浏览器中的隐身或隐私窗口，以确保 Service Worker 不会从以前的残留状态中读取数据，否则可能导致意外的行为。

Tip: When testing Angular service workers, it's a good idea to use an incognito or private window in your browser to ensure the service worker doesn't end up reading from a previous leftover state, which can cause unexpected behavior.

模拟网络出问题link

Simulating a network issuelink

要想模拟网络出问题的情况，可以为你的应用禁用网络交互。在 Chrome 中：

To simulate a network issue, disable network interaction for your application. In Chrome:

1. 选择 Tools > Developer Tools （从右上角的 Chrome 菜单）。

   Select Tools > Developer Tools (from the Chrome menu located at the top right corner).

2. 进入 Network 页。

   Go to the Network tab.

3. 勾选 Offline 复选框。

   Check the Offline box.

现在，本应用不能再和网络进行交互了。

Now the app has no access to network interaction.

对于那些不使用 Angular Service Worker 的应用，现在刷新将会显示 Chrome 的“网络中断”页，提示“没有可用的网络连接”。

For applications that do not use the Angular service worker, refreshing now would display Chrome's Internet disconnected page that says "There is no Internet connection".

有了 Angular Service Worker，本应用的行为就不一样了。刷新时，页面会正常加载。

With the addition of an Angular service worker, the application behavior changes. On a refresh, the page loads normally.

如果你看看 Network 页，就会发现 Service Worker 是激活的。

If you look at the Network tab, you can verify that the service worker is active.

注意，在 “Size” 列中，请求的状态是 (from ServiceWorker)。 这表示该资源不是从网络上加载的，而是从 Service Worker 的缓存中。

Notice that under the "Size" column, the requests state is (from ServiceWorker). This means that the resources are not being loaded from the network. Instead, they are being loaded from the service worker's cache.

什么被缓存了？link

What's being cached?link

注意，浏览器要渲染的所有这些文件都被缓存了。 ngsw-config.json 样板文件被配置成了要缓存 CLI 用到的那些文件：

Notice that all of the files the browser needs to render this application are cached. The ngsw-config.json boilerplate configuration is set up to cache the specific resources used by the CLI:

• index.html.

• favicon.ico.

• 构建结果（JS 和 CSS 包）。

  Build artifacts (JS and CSS bundles).

• assets 下的所有文件。

  Anything under assets.

修改你的应用link

Making changes to your applicationlink

现在，你已经看到了 Service Worker 如何缓存你的应用，接下来的步骤讲它如何进行更新。

Now that you've seen how service workers cache your application, the next step is understanding how updates work.

1. 如果你正在隐身窗口中测试，请打开第二个空白页。这会让该隐身窗口和缓存的状态在测试期间持续活着。

   If you're testing in an incognito window, open a second blank tab. This will keep the incognito and the cache state alive during your test.

2. 关闭该应用的页面，而不是整个窗口。这也会同时关闭开发者工具。

   Close the application tab, but not the window. This should also close the Developer Tools.

3. 关闭 http-server。

   Shut down http-server.

4. 接下来，对应用进行一些修改，并且观察 Service Worker 安装这些更新。

   Next, make a change to the application, and watch the service worker install the update.

5. 打开 src/app/app.component.html 供编辑。

   Open src/app/app.component.html for editing.

6. 把文本 Welcome to {{title}}! 改为 Bienvenue à {{title}}!。

   Change the text Welcome to {{title}}! to Bienvenue à {{title}}!.

7. 再次构建并运行此服务器：

   Build and run the server again:

      
        content_copy
      
      ng build --prod
http-server -p 8080 -c-1 dist/<project-name>
    

在浏览器中更新你的应用link

Updating your application in the browserlink

现在，看看浏览器和 Service Worker 如何处理这个更新后的应用。

Now look at how the browser and service worker handle the updated application.

1. 再次在同一个窗口中打开 http://localhost:8080，发生了什么？

   Open http://localhost:8080 again in the same window. What happens?

错在哪里？哪里也没错，真的。Angular Service Worker 正在做自己的工作，并且用它已经安装过的版本提供服务，虽然，已经有新版本可用了。由于更关注速度，所以 Service Worker 并不会在启动它已经缓存过的版本之前先等待检查更新。

What went wrong? Nothing, actually. The Angular service worker is doing its job and serving the version of the application that it has installed, even though there is an update available. In the interest of speed, the service worker doesn't wait to check for updates before it serves the application that it has cached.

如果你看看 http-server 的 log，就会发现 Service Worker 请求了 /ngsw.json 文件，这是 Service Worker 正在检查更新。

If you look at the http-server logs, you can see the service worker requesting /ngsw.json. This is how the service worker checks for updates.

2. 刷新页面。

   Refresh the page.

Service Worker 在后台安装好了这个更新后的版本，下次加载或刷新页面时，Service Worker 就切换到最新的版本了。

The service worker installed the updated version of your app in the background, and the next time the page is loaded or reloaded, the service worker switches to the latest version.

关于 Angular Service Worker 的更多信息link

More on Angular service workerslink

你可能还对下列内容感兴趣：

You may also be interested in the following:

• 与 Service Worker 通讯。

  Communicating with service workers.