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

Workbox v3에서 v4로 이전

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

브레이킹 체인지

사전 캐싱 워크박스

미리 캐시된 항목의 이름 지정 규칙이 업데이트되었습니다. 이제 URL에 버전 관리 정보가 필요한 항목 (즉, 미리 캐시 매니페스트에 revision 필드가 포함된 항목)의 경우 해당 버전 관리 정보가 캐시 키의 일부로 저장되며 원래 URL에 추가된 특수 __WB_REVISION__ URL 쿼리 매개변수에 저장됩니다. 이전에는 이 정보가 IndexedDB를 사용하여 캐시 키와 별도로 저장되었습니다.

가장 일반적인 사용 사례인 workbox.precaching.precacheAndRoute()를 통해 미리 캐싱을 활용하는 개발자는 서비스 워커 구성을 변경할 필요가 없습니다. Workbox v4로 업그레이드하면 사용자의 캐시된 애셋이 새 캐시 키 형식으로 자동으로 이전되며 앞으로는 미리 캐시된 리소스가 이전과 동일한 방식으로 계속 제공됩니다.

캐시 키 직접 사용

일부 개발자는 workbox.precaching.precacheAndRoute() 컨텍스트 외부에서 사전 캐시 항목에 직접 액세스해야 할 수 있습니다. 예를 들어 실제 이미지를 네트워크에서 가져올 수 없는 경우 '대체' 응답으로 사용하게 될 이미지를 미리 캐시할 수 있습니다.

Workbox v4부터 사전 캐시된 자산을 이런 방식으로 사용하는 경우, 원래 URL을 캐시된 항목을 읽는 데 사용할 수 있는 해당 캐시 키로 변환하기 위한 추가 단계를 수행해야 합니다. workbox.precaching.getCacheKeyForURL(originURL)를 호출하면 됩니다.

예를 들어 'fallback.png'가 미리 캐시되었다고 가정해 보겠습니다.

const imageFallbackCacheKey =
  workbox.precaching.getCacheKeyForURL('fallback.png');

workbox.routing.setCatchHandler(({event}) => {
  switch (event.request.destination) {
    case 'image':
      return caches.match(imageFallbackCacheKey);
      break;
    // ...other fallback logic goes here...
  }
});

이전에 캐시된 오래된 데이터 정리

Workbox v4에서 프리캐싱이 변경되었으므로 이전 버전의 Workbox로 만든 이전 프리캐시가 호환되지 않습니다. 기본적으로 이러한 리소스는 그대로 유지되며 Workbox v3에서 Workbox v4로 업그레이드하면 미리 캐시된 모든 리소스의 사본이 두 개가 됩니다.

이를 방지하려면 workbox.precaching.cleanupOutdatedCaches() 호출을 서비스 워커에 직접 추가하거나 GenerateSW 모드에서 빌드 도구를 사용하는 경우 새 cleanupOutdatedCaches: true 옵션을 설정하면 됩니다. 캐시 정리 로직은 이전의 미리 캐시를 찾기 위해 캐시 이름 지정 규칙을 기반으로 작동하며 개발자는 이러한 규칙을 재정의할 수 있으므로 안전을 위해 기본적으로 이 기능을 사용 설정하지 않았습니다.

삭제와 관련된 거짓양성 등 이 기능을 사용할 때 문제가 발생한 개발자는 Google에 알려주세요.

매개변수 대문자 사용

workbox.precaching.precacheAndRoute() 및 workbox.precaching.addRoute()에 전달할 수 있는 두 가지 선택적 매개변수의 이름이 변경되었습니다. 이는 전체 대문자 표기 규칙을 표준화하기 위한 조치입니다. 이제 ignoreUrlParametersMatching가 ignoreURLParametersMatching, cleanUrls가 이제 cleanURLs입니다.

workbox-strategies

workbox-strategies에서 핸들러의 인스턴스를 만드는 거의 동일한 두 가지 방법이 있습니다. 전략의 생성자를 명시적으로 호출하는 대신 팩토리 메서드가 지원 중단됩니다.

// This factory method syntax has been deprecated:
const networkFirstStrategy = workbox.strategies.networkFirst({...});

// Instead, use the constructor directly:
// (Note that the class name is Uppercase.)
const networkFirstStrategy = new workbox.strategies.NetworkFirst({...});

팩토리 메서드 문법은 v4에서 계속 작동하지만 이를 사용하면 경고가 기록되므로 개발자는 향후 v5 출시에서 지원이 중단되기 전에 미리 이전하는 것이 좋습니다.

workbox-background-sync

개발자가 요청이 대기열에 추가되고 재생되는 방식을 더 유연하게 제어할 수 있도록 workbox.backgroundSync.Queue 클래스가 다시 작성되었습니다.

v3에서는 Queue 클래스에 요청을 대기열에 추가하는 단일 방법 (addRequest() 메서드)이 있었지만 대기열을 수정하거나 요청을 삭제하는 방법은 없었습니다.

v4에서는 addRequests() 메서드가 삭제되고 다음과 같은 배열과 유사한 메서드가 추가되었습니다.

pushRequest()
popRequest()
shiftRequest()
unshiftRequest()

v3에서 Queue 클래스는 요청이 재생될 때 이를 관찰할 수 있는 여러 콜백 (requestWillEnqueue, requestWillReplay, queueDidReplay)도 허용했지만, 대부분의 개발자는 관찰 외에도 동적으로 수정, 재정렬 또는 개별 요청을 취소하는 기능을 포함하여 재생목록이 재생되는 방식을 제어하고자 했습니다.

v4에서는 이러한 콜백이 삭제되고 브라우저에서 재생을 시도할 때마다 호출되는 단일 onSync 콜백이 대신 사용됩니다. 기본적으로 onSync 콜백은 replayRequests()를 호출하지만 재생 프로세스를 더 세부적으로 제어해야 하는 경우 위에 나열된 배열과 같은 메서드를 사용하여 원하는 대로 재생목록을 재생할 수 있습니다.

다음은 맞춤 재생 로직의 예입니다.

const queue = new workbox.backgroundSync.Queue('my-queue-name', {
  onSync: async ({queue}) => {
    let entry;
    while ((entry = await this.shiftRequest())) {
      try {
        await fetch(entry.request);
      } catch (error) {
        console.error('Replay failed for request', entry.request, error);
        await this.unshiftRequest(entry);
        return;
      }
    }
    console.log('Replay complete!');
  },
});

마찬가지로 workbox.backgroundSync.Plugin 클래스는 내부적으로 Queue 인스턴스를 만들므로 Queue 클래스와 동일한 인수를 허용하므로 동일한 방식으로 변경되었습니다.

Workbox-expiration(작업 상자 만료)

npm 패키지 이름이 다른 모듈에 사용되는 이름 지정 규칙과 일치하도록 workbox-expiration로 이름이 변경되었습니다. 이 패키지는 현재 지원 중단된 이전 workbox-cache-expiration 패키지와 기능적으로 동일합니다.

workbox-broadcast-update

npm 패키지의 이름이 다른 모듈에 사용되는 명명 규칙과 일치하도록 workbox-broadcast-update로 변경되었습니다. 이 패키지는 현재 지원 중단된 이전 workbox-broadcast-cache-update 패키지와 기능적으로 동일합니다.

workbox-core

Workbox v3에서는 로그 수준의 세부정보 수준을 workbox.core.LOG_LEVELS enum의 값 중 하나를 전달하는 workbox.core.setLogLevel() 메서드를 통해 제어할 수 있습니다. workbox.core.logLevel를 통해 현재 로그 수준을 읽을 수도 있습니다.

Workbox v4에서는 모든 최신 개발자 도구가 다양한 로그 필터링 기능과 함께 제공되므로 이러한 모든 기능이 삭제되었습니다 (Chrome 개발자 도구의 콘솔 출력 필터링 참고).

workbox-sw

이전에 workbox 네임스페이스 (workbox-sw 모듈에 해당)에 직접 노출된 두 메서드가 대신 workbox.core로 이동했습니다. workbox.skipWaiting()는 workbox.core.skipWaiting()가 되었고 마찬가지로 workbox.clientsClaim()는 workbox.core.clientsClaim()가 되었습니다.

빌드 도구 구성

workbox-cli, workbox-build 또는 workbox-webpack-plugin에 전달할 수 있는 일부 옵션의 이름이 변경되었습니다. 옵션 이름에 'Url'이 사용된 경우 'URL'로 대체되었습니다. 즉, 다음과 같은 옵션 이름을 사용하는 것이 좋습니다.

dontCacheBustURLsMatching
ignoreURLParametersMatching
modifyURLPrefix
templatedURLs

이러한 옵션 이름의 'URL' 변형은 v4에서 계속 작동하지만 경고 메시지가 표시됩니다. 개발자는 v5 출시 전에 이전하는 것이 좋습니다.

새로운 기능

workbox-window

새로운 workbox-window 모듈은 서비스 워커 등록 및 업데이트 감지 프로세스를 간소화하고, 서비스 워커에서 실행되는 코드와 웹 앱의 window 컨텍스트에서 실행되는 코드 간의 표준 통신 수단을 제공합니다.

workbox-window 사용은 선택사항이지만 개발자가 유용하다고 생각하고 적절한 경우 이를 사용하도록 직접 작성한 로직의 일부를 이전하는 것을 고려해 보시기 바랍니다. workbox-window 사용에 관한 자세한 내용은 모듈 가이드를 참고하세요.

이전 예시

Workbox v3에서 v4로의 실제 이전 예는 이 Pull 요청에서 확인할 수 있습니다.

도움 받기

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