이 페이지는 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에서 핸들러 인스턴스를 생성하는 데는 거의 동일한 방법이 두 가지 있습니다. 전략의 생성자를 명시적으로 호출하기 위해 팩토리 메서드를 지원 중단합니다.

// 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.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 클래스와 동일한 인수를 허용하므로 동일한 방식으로 변경되었습니다.

작업 상자 만료

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

작업 상자 브로드캐스트 업데이트

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

작업 상자 코어

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

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

작업 상자-스웨덴

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

workbox-window 사용은 선택사항이지만 개발자들이 유용하게 사용할 수 있기를 바라며, 필요한 경우 필기 입력 로직 중 일부를 이전하여 사용하는 것이 좋습니다. workbox-window 사용에 관한 자세한 내용은 모듈 가이드를 참고하세요.

이전 예시

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

지원 받기

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