이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Workbox v5에서 v6으로 이전

이 가이드에서는 Workbox v6에 도입된 브레이킹 체인지와 Workbox v5에서 업그레이드할 때 변경해야 하는 사항에 대한 예를 중점적으로 설명합니다.

이전 버전과 호환되지 않는 변경사항

워크박스 코어

workbox-core의 skipWaiting() 메서드는 더 이상 install 핸들러를 추가하지 않으며 self.skipWaiting()를 호출하는 것과 동일합니다.

이제 Workbox v7에서 skipWaiting()가 삭제될 수 있으므로 이제부터는 self.skipWaiting()를 대신 사용하세요.

작업 상자 사전 캐싱

HTTP 리디렉션에 해당하는 URL에 대한 교차 출처 HTML 문서를 더 이상 workbox-precaching로 탐색 요청을 충족하는 데 사용할 수 없습니다. 이 시나리오는 일반적으로 드물게 사용됩니다.
이제 특정 요청에 관해 사전 캐시된 응답을 조회할 때 workbox-precaching에서 fbclid URL 쿼리 매개변수를 무시합니다.
이제 PrecacheController 생성자는 문자열이 아닌 특정 속성이 매개변수로 있는 객체를 가져옵니다. 이 객체는 cacheName (v5에서 생성자에 전달된 문자열과 동일한 용도로 사용), plugins (v5의 addPlugins() 메서드 대체), fallbackToNetwork (v5에서 createHandler() 및 `createHandlerBoundToURL()에 전달된 유사한 옵션 대체) 등의 속성을 지원합니다.
이제 PrecacheController의 install() 및 activate() 메서드는 정확히 하나의 매개변수를 사용하며 각각 상응하는 InstallEvent 또는 ActivateEvent로 설정해야 합니다.
addRoute() 메서드가 PrecacheController에서 삭제되었습니다. 대신 새 PrecacheRoute 클래스를 사용하여 등록할 수 있는 경로를 만들 수 있습니다.
precacheAndRoute() 메서드가 PrecacheController에서 삭제되었습니다. 이 메서드는 workbox-precaching 모듈에서 내보낸 정적 도우미 메서드로 여전히 존재합니다. 대신 PrecacheRoute을(를) 사용할 수 있으므로 삭제되었습니다.
createMatchCalback() 메서드가 PrecacheController에서 삭제되었습니다. 대신 새 PrecacheRoute를 사용할 수 있습니다.
createHandler() 메서드가 PrecacheController에서 삭제되었습니다. 대신 PrecacheController 객체의 strategy 속성을 사용하여 요청을 처리할 수 있습니다.
createHandler() 정적 내보내기가 workbox-precaching 모듈에서 이미 삭제되었습니다. 대신 개발자는 PrecacheController 인스턴스를 구성하고 strategy 속성을 사용해야 합니다.
precacheAndRoute()에 등록된 경로는 이제 내부적으로 workbox-routing의 Router 클래스를 사용하는 '실제' 경로입니다. 이로 인해 registerRoute() 및 precacheAndRoute() 호출을 인터리브 처리하면 경로의 평가 순서가 달라질 수 있습니다.

워크박스 라우팅

이제 setDefaultHandler() 메서드는 적용되는 HTTP 메서드에 상응하는 두 번째 매개변수(선택사항)를 사용하며 기본값은 'GET'입니다.

setDefaultHandler()를 사용하고 모든 요청이 GET인 경우에는 변경할 필요가 없습니다.
GET (POST, PUT 등)이 아닌 요청이 있는 경우 setDefaultHandler()는 더 이상 이러한 요청을 일치시키지 않습니다.

빌드 구성

workbox-build 및 workbox-cli의 getManifest 및 injectManifest 모드의 mode 옵션은 지원되지 않아 삭제되었습니다. 이는 InjectManifest 플러그인에서 mode를 지원하는 workbox-webpack-plugin에는 적용되지 않습니다.

빌드 도구에 Node.js v10 이상 필요

v10 이전의 Node.js 버전은 workbox-webpack-plugin, workbox-build 또는 workbox-cli에서 더 이상 지원되지 않습니다. v8 이전 버전의 Node.js를 실행하는 경우 런타임을 지원되는 버전으로 업데이트하세요.

새로운 개선사항

작업 상자 전략

Workbox v6에서는 타사 개발자가 자신만의 Workbox 전략을 정의할 수 있는 새로운 방법을 도입했습니다. 이를 통해 서드 파티 개발자는 요구사항을 완전히 충족하는 방식으로 Workbox를 확장할 수 있습니다.

새 전략 기본 클래스

v6에서는 모든 Workbox 전략 클래스가 새로운 Strategy 기본 클래스를 확장해야 합니다. 기본으로 제공되는 모든 전략은 이를 지원하기 위해 다시 작성되었습니다.

Strategy 기본 클래스는 다음 두 가지 주요 작업을 담당합니다.

모든 전략 핸들러에 공통된 플러그인 수명 주기 콜백을 호출합니다 (예: 핸들러가 시작, 응답, 종료될 때).
전략에서 처리하는 각 개별 요청의 상태를 관리할 수 있는 '핸들러' 인스턴스를 만듭니다.

새 'handler' 클래스

이전에는 내부 모듈에서 fetchWrapper 및 cacheWrapper를 호출했습니다. 이는 이름에서 알 수 있듯이 다양한 가져오기 및 캐시 API를 후크를 사용하여 수명 주기에 래핑합니다. 이는 현재 플러그인이 작동할 수 있도록 하는 메커니즘이지만 개발자에게 노출되지는 않습니다.

새 '핸들러' 클래스인 StrategyHandler는 맞춤 전략이 fetch() 또는 cacheMatch()를 호출하고 전략 인스턴스에 추가된 플러그인을 자동으로 호출할 수 있도록 이러한 메서드를 노출합니다.

또한 이 클래스를 사용하면 개발자가 자신의 전략에 맞는 맞춤형 수명 주기 콜백을 추가할 수 있으며, 기존 플러그인 인터페이스와 '단순하게 작동'합니다.

새 플러그인 수명 주기 상태

Workbox v5에서 플러그인은 스테이트리스(Stateless)입니다. 즉, /index.html 요청이 requestWillFetch 및 cachedResponseWillBeUsed 콜백을 모두 트리거하면 이 두 콜백은 서로 통신하거나 동일한 요청에 의해 트리거되었음을 알 수 없습니다.

v6에서는 모든 플러그인 콜백에도 새로운 state 객체가 전달됩니다. 이 상태 객체는 이 특정 플러그인 객체와 이 특정 전략 호출 (예: handle() 호출)에만 고유합니다. 이를 통해 개발자는 한 콜백이 동일한 플러그인의 다른 콜백이 수행한 작업에 따라 조건부로 작업을 수행할 수 있는 플러그인을 작성할 수 있습니다 (예: requestWillFetch 및 fetchDidSucceed 또는 fetchDidFail 실행 간의 시간 델타 계산).

새 플러그인 수명 주기 콜백

개발자가 플러그인 수명 주기 상태를 완전히 활용할 수 있도록 새로운 플러그인 수명 주기 콜백을 추가했습니다.

handlerWillStart: 핸들러 로직 실행이 시작되기 전에 호출됩니다. 이 콜백은 초기 핸들러 상태 (예: 시작 시간 기록)를 설정하는 데 사용할 수 있습니다.
handlerWillRespond: 전략 handle() 메서드가 응답을 반환하기 전에 호출됩니다. 이 콜백은 응답을 경로 핸들러 또는 다른 맞춤 로직으로 반환하기 전에 수정하는 데 사용할 수 있습니다.
handlerDidRespond: 전략의 handle() 메서드가 응답을 반환한 후에 호출됩니다. 이 콜백은 예를 들어 다른 플러그인에 의해 변경된 후 등에 최종 응답 세부정보를 기록하는 데 사용할 수 있습니다.
handlerDidComplete: 이 전략의 호출에서 이벤트에 추가된 전체 기간 연장 프로미스가 완료된 후 호출됩니다. 이 콜백은 계산하기 위해 핸들러가 완료될 때까지 기다려야 하는 모든 데이터 (예: 캐시 적중 상태, 캐시 지연 시간, 네트워크 지연 시간)를 보고하는 데 사용할 수 있습니다.
handlerDidError: 핸들러가 모든 소스에서 유효한 응답을 제공할 수 없는 경우 호출됩니다. 이 콜백은 네트워크 오류의 대안으로 '대체' 콘텐츠를 제공하는 데 사용할 수 있습니다.

자체 맞춤 전략을 구현하는 개발자는 이러한 콜백을 직접 호출하는 것에 관해 걱정할 필요가 없습니다. 이 모든 작업은 새로운 Strategy 기본 클래스에 의해 처리됩니다.

핸들러의 더 정확한 TypeScript 유형

다양한 콜백 메서드의 TypeScript 정의가 정규화되었습니다. 이렇게 하면 TypeScript를 사용하고 자체 코드를 작성하여 핸들러를 구현하거나 호출하는 개발자에게 더 나은 환경이 제공됩니다.

작업 상자-창

새 messageSkipWaiting() 메서드

'대기 중' 서비스 워커에 활성화를 지시하는 프로세스를 간소화하기 위해 새 메서드 messageSkipWaiting()가 workbox-window 모듈에 추가되었습니다. 이를 통해 다음과 같은 몇 가지 사항이 개선되었습니다.

Workbox에서 생성한 서비스 워커가 skipWaiting()를 트리거하기 위해 확인하는 사실상의 표준 메시지 본문인 {type: 'SKIP_WAITING'}를 사용하여 postMessage()를 호출합니다.
workbox-window가 등록된 서비스 워커와 동일한 서비스 워커가 아니더라도 이 메시지를 게시할 올바른 '대기 중' 서비스 워커를 선택합니다.

isExternal 속성으로 '외부' 이벤트 삭제

workbox-window의 모든 "external" 이벤트가 isExternal 속성이 true로 설정된 '일반' 이벤트 대신 삭제되었습니다. 이렇게 하면 구분에 관심이 있는 개발자는 이 속성을 계속 감지할 수 있고 알 필요가 없는 개발자는 속성을 무시할 수 있습니다.

'사용자에게 페이지 새로고침 제공' 레시피 클리너

위의 두 가지 변경사항 덕분에 '사용자에게 페이지 새로고침 제공' 레시피를 단순화할 수 있습니다.

MULTI_LINE_CODE_PLACEHOLDER_0

워크박스 라우팅

새로운 불리언 매개변수 sameOrigin가 workbox-routing에 사용되는 matchCallback 함수에 전달됩니다. 요청이 동일한 출처 URL에 대한 요청이면 true로 설정되고 그렇지 않으면 false로 설정됩니다.

이렇게 하면 일반적인 상용구가 간소화됩니다.

MULTI_LINE_CODE_PLACEHOLDER_1

Workbox-expiration의 matchOptions

이제 workbox-expiration에서 matchOptions를 설정할 수 있으며 이는 CacheQueryOptions로 기본 cache.delete() 호출에 전달됩니다. 대부분의 개발자는 이 작업을 수행할 필요가 없습니다.

작업 상자 사전 캐싱

워크박스 전략 사용

workbox-strategies를 베이스로 사용하도록 workbox-precaching를 다시 작성했습니다. 이로 인해 브레이킹 체인지가 발생하지 않아야 하며, 두 모듈이 네트워크와 캐시에 액세스하는 방식에 있어 장기적으로 더 나은 일관성으로 이어져야 합니다.

이제 사전 캐싱을 통해 항목을 일괄 처리하지 않고 하나씩 처리합니다.

사전 캐시 매니페스트의 항목을 한 번에 모두 요청하고 캐시하려고 시도하는 대신 (제한 방법을 알아내기 위해 브라우저에 맡기는) 한 번에 하나의 항목만 요청되고 캐시되도록 workbox-precaching가 업데이트되었습니다.

이렇게 하면 사전 캐싱 중에 net::ERR_INSUFFICIENT_RESOURCES 오류가 발생할 가능성이 줄어들고 사전 캐싱과 웹 앱의 동시 요청 사이의 대역폭 경합도 줄어듭니다.

PrecacheFallbackPlugin을 사용하면 더 쉬운 오프라인 대체 가능

이제 workbox-precaching에 v6에 추가된 새로운 handlerDidError 수명 주기 메서드를 구현하는 PrecacheFallbackPlugin가 포함됩니다.

이렇게 하면 응답을 사용할 수 없을 때 사전 캐시된 URL을 특정 전략에 대한 '대체'로 쉽게 지정할 수 있습니다. 플러그인은 필요한 수정 매개변수를 포함하여 사전 캐시된 URL에 대한 올바른 캐시 키를 올바르게 구성합니다.

다음은 NetworkOnly 전략이 탐색 요청에 관한 응답(즉, 맞춤 오프라인 HTML 페이지 표시)을 생성할 수 없을 때 사전 캐시된 /offline.html로 응답하는 데 사용하는 샘플입니다.

MULTI_LINE_CODE_PLACEHOLDER_2

런타임 캐싱의 `precacheFallback`

서비스 워커를 직접 작성하는 대신 generateSW를 사용하여 서비스 워커를 만드는 경우 runtimeCaching에 새로운 precacheFallback 구성 옵션을 사용하여 동일한 작업을 할 수 있습니다.

{
  // ... other generateSW config options...
  runtimeCaching: [{
    urlPattern: ({request}) => request.mode === 'navigate',
    handler: 'NetworkOnly',
    options: {
      precacheFallback: {
        // This URL needs to be included in your precache manifest.
        fallbackURL: '/offline.html',
      },
    },
  }],
}

도움말 보기

대부분의 마이그레이션은 간단할 것으로 예상됩니다. 이 가이드에서 다루지 않은 문제가 발생하면 GitHub에서 문제를 열어 알려주세요.

Workbox v5에서 v6으로 이전

이전 버전과 호환되지 않는 변경사항

워크박스 코어

작업 상자 사전 캐싱

워크박스 라우팅

빌드 구성

빌드 도구에 Node.js v10 이상 필요

새로운 개선사항

작업 상자 전략

새 전략 기본 클래스

새 'handler' 클래스

새 플러그인 수명 주기 상태

새 플러그인 수명 주기 콜백

핸들러의 더 정확한 TypeScript 유형

작업 상자-창

새 messageSkipWaiting() 메서드

isExternal 속성으로 '외부' 이벤트 삭제

'사용자에게 페이지 새로고침 제공' 레시피 클리너

워크박스 라우팅

Workbox-expiration의 matchOptions

작업 상자 사전 캐싱

워크박스 전략 사용

이제 사전 캐싱을 통해 항목을 일괄 처리하지 않고 하나씩 처리합니다.

PrecacheFallbackPlugin을 사용하면 더 쉬운 오프라인 대체 가능

런타임 캐싱의 precacheFallback

도움말 보기

런타임 캐싱의 `precacheFallback`