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

Workbox v5에서 v6으로 이전

이 가이드에서는 Workbox v6에 도입된 브레이킹 체인지에 중점을 두고 Workbox v5에서 업그레이드할 때 변경해야 하는 내용의 예를 보여줍니다.

브레이킹 체인지

workbox-core

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-strategies

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

새 전략 기본 클래스

v6에서는 모든 Workbox 전략 클래스가 새 Strategy 기본 클래스를 확장해야 합니다. 이를 지원하도록 모든 내장 전략이 다시 작성되었습니다.

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

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

새 '핸들러' 클래스

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

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

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

새 플러그인 수명 주기 상태

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

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

새로운 플러그인 수명 주기 콜백

개발자가 플러그인 수명 주기 상태를 최대한 활용할 수 있도록 새로운 플러그인 수명 주기 콜백이 추가되었습니다.

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

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

핸들러의 더 정확한 TypeScript 유형

다양한 콜백 메서드의 TypeScript 정의가 정규화되었습니다. 이를 통해 TypeScript를 사용하고 핸들러를 구현하거나 호출하기 위해 자체 코드를 작성하는 개발자의 환경이 개선될 것입니다.

workbox-window

새 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를 설정할 수 있으며, 그러면 matchOptions가 기본 cache.delete() 호출에 CacheQueryOptions로 전달됩니다. 대부분의 개발자는 이 작업을 수행할 필요가 없습니다.

사전 캐싱 워크박스

workbox-strategies 사용

workbox-precaching가 workbox-strategies를 기반으로 사용하도록 재작성되었습니다. 이로 인해 중대한 변경사항이 발생하지 않으며 두 모듈이 네트워크 및 캐시에 액세스하는 방식의 장기적인 일관성이 개선됩니다.

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

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으로 이전

브레이킹 체인지

workbox-core

사전 캐싱 워크박스

워크박스-라우팅

빌드 구성

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

새로운 개선사항

workbox-strategies

새 전략 기본 클래스

새 '핸들러' 클래스

새 플러그인 수명 주기 상태

새로운 플러그인 수명 주기 콜백

핸들러의 더 정확한 TypeScript 유형

workbox-window

새 messageSkipWaiting() 메서드

isExternal 속성을 위해 '외부' 이벤트 삭제

더 깔끔한 '사용자에게 페이지 새로고침 제공' 리시피

워크박스-라우팅

workbox-expiration의 matchOptions

사전 캐싱 워크박스

workbox-strategies 사용

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

PrecacheFallbackPlugin을 사용하면 더 쉽게 오프라인 대체를 사용할 수 있습니다.

런타임 캐싱의 precacheFallback

도움말 보기

런타임 캐싱의 `precacheFallback`