Di chuyển từ Workbox phiên bản 2 sang phiên bản 3

Hướng dẫn này tập trung vào những thay đổi có thể gây lỗi được giới thiệu trong Workbox v3, kèm theo ví dụ về những thay đổi bạn cần thực hiện khi nâng cấp từ chế độ thiết lập Workbox phiên bản 2.

Nếu bạn hiện đang sử dụng kết hợp sw-precache/sw-toolbox cũ và lần đầu tiên muốn chuyển đổi sang Workbox, hãy tham khảo hướng dẫn di chuyển khác sau đây.

Nền phiên bản 3

Bản phát hành v3 của Workbox cho thấy việc tái cấu trúc đáng kể cơ sở mã hiện có. Mục tiêu tổng quát là:

  • Giảm thiểu kích thước của Workbox. Lượng mã thời gian chạy dịch vụ được tải xuống và thực thi đã giảm. Thay vì chọn áp dụng cho mọi người trong một gói nguyên khối, hệ thống chỉ nhập mã cho các tính năng cụ thể mà bạn đang sử dụng trong thời gian chạy.
  • Hộp làm việc có CDN. Chúng tôi cung cấp dịch vụ lưu trữ CDN dựa trên Google Cloud Storage, được hỗ trợ đầy đủ làm lựa chọn chuẩn để truy cập vào thư viện thời gian chạy Workbox, giúp việc thiết lập và chạy Workbox trở nên dễ dàng hơn.
  • Quy trình gỡ lỗi và ghi nhật ký hiệu quả hơn. Trải nghiệm gỡ lỗi và ghi nhật ký đã được cải thiện đáng kể. Theo mặc định, nhật ký gỡ lỗi được bật bất cứ khi nào Workbox được sử dụng qua nguồn gốc localhost, đồng thời mọi nhật ký và câu nhận định đều bị xoá khỏi bản dựng chính thức. Ví dụ về tính năng ghi nhật ký gỡ lỗi do Workbox phiên bản 3 cung cấp.
  • Trình bổ trợ gói web đã được cải tiến. workbox-webpack-plugin tích hợp chặt chẽ hơn với quy trình xây dựng gói web, cho phép trường hợp sử dụng không cấu hình khi bạn muốn lưu trước tất cả thành phần trong quy trình xây dựng vào bộ nhớ đệm.

Việc đạt được các mục tiêu này và dọn dẹp một số khía cạnh của giao diện trước đây có vẻ khó khăn hoặc dẫn đến phản mẫu, buộc phải đưa ra một số thay đổi có thể gây lỗi trong bản phát hành v3.

Thay đổi có thể gây lỗi

Cấu hình bản dựng

Những thay đổi sau ảnh hưởng đến hành vi của tất cả các công cụ xây dựng (workbox-build, workbox-cli, workbox-webpack-plugin), những công cụ này dùng chung một tập hợp các tuỳ chọn cấu hình.

  • Tên trình xử lý 'fastest' trước đây hợp lệ và được coi là biệt hiệu cho 'staleWhileRevalidate' khi định cấu hình runtimeCaching. Phương thức này không còn hợp lệ và nhà phát triển nên chuyển trực tiếp sang sử dụng 'staleWhileRevalidate'.
  • Một số tên thuộc tính runtimeCaching.options đã được cập nhật và việc xác thực thông số bổ sung sẽ được áp dụng. Việc xác thực tham số bổ sung sẽ khiến bản dựng không hoạt động nếu sử dụng cấu hình không hợp lệ. Xem tài liệu dành cho runtimeCaching để biết danh sách các tuỳ chọn hiện được hỗ trợ.

đồng bộ hoá nền hộp công việc

  • Tham số cấu hình maxRetentionTime hiện được hiểu là số phút, thay vì số mili giây.
  • Hiện tại, có một chuỗi bắt buộc đại diện cho tên hàng đợi. Chuỗi này phải được chuyển vào dưới dạng tham số đầu tiên khi tạo Trình bổ trợ hoặc lớp độc lập. (Trước đó, tham số này đã được truyền vào dưới dạng thuộc tính của các tuỳ chọn.) Tham khảo tài liệu này để biết giao diện API đã cập nhật.

workbox-broadcast-cache-update

  • Hiện tại, có một chuỗi bắt buộc đại diện cho tên kênh phải được chuyển vào dưới dạng tham số đầu tiên khi tạo Trình bổ trợ hoặc lớp độc lập.

Ví dụ: trong phiên bản 2, bạn sẽ khởi chạy lớp Plugin như sau:

new workbox.broadcastCacheUpdate.BroadcastCacheUpdatePlugin({
  channelName: 'cache-updates',
  headersToCheck: ['etag'],
});

Cách sử dụng tương đương trong phiên bản 3 là:

new workbox.broadcastUpdate.Plugin('cache-updates', {headersToCheck: ['etag']});

Tham khảo tài liệu này để biết giao diện API đã cập nhật.

bản dựng hộp làm việc

  • Theo mặc định, việc so khớp mẫu glob giờ đây sẽ được thực hiện bằng các tuỳ chọn follow: true (theo các đường liên kết tượng trưng) và strict: true (ít chấp nhận các lỗi "bất thường"). Bạn có thể tắt một trong hai và quay lại hành vi trước đó bằng cách thiết lập globFollow: false và/hoặc globStrict: false trong cấu hình bản dựng.
  • Các hàm trong workbox-build đều trả về một thuộc tính bổ sung là warnings trong phản hồi mà chúng trả về. Hiện tại, bạn có thể sử dụng một số trường hợp được coi là lỗi nghiêm trọng trong phiên bản 2, nhưng sẽ được báo cáo qua warnings (đây là một mảng chuỗi).

Trong phiên bản 2, bạn có thể gọi generateSW như sau:

const workboxBuild = require('workbox-build');

workboxBuild.generateSW({...})
  .then(({count, size}) => console.log(`Precached ${count} files, totaling ${size} bytes.`))
  .catch((error) => console.error(`Something went wrong: ${error}`));

Mặc dù có thể sử dụng cùng một mã trong phiên bản 3, bạn nên kiểm tra mọi warnings và ghi lại chúng:

const workboxBuild = require('workbox-build');

workboxBuild.generateSW({...})
  .then(({count, size, warnings}) => {
    for (const warning of warnings) {
      console.warn(warning);
    }
    console.log(`Precached ${count} files, totalling ${size} bytes.`);
  })
  .catch((error) => console.error(`Something went wrong: ${error}`));
  • Các nhà phát triển viết hàm ManifestTransform tuỳ chỉnh của riêng mình trong phiên bản 2 cần trả về mảng tệp kê khai trong một đối tượng (tức là thay vì return manifestArray;, bạn nên sử dụng return {manifest: manifestArray};).mĐiều này cho phép trình bổ trợ của bạn bao gồm một thuộc tính warnings không bắt buộc. Thuộc tính này phải là một mảng chuỗi chứa thông tin cảnh báo không nghiêm trọng.

Nếu bạn đang viết ManifestTransform tuỳ chỉnh trong phiên bản 2, thì đoạn mã như sau:

const cdnTransform = manifestEntries => {
  return manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
};

có phiên bản v3 tương đương với:

const cdnTransform = manifestEntries => {
  const manifest = manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
  return {manifest, warnings: []};
};
  • Hàm getFileManifestEntries() đã được đổi tên thành getManifest() và lời hứa được trả về hiện bao gồm thông tin bổ sung về các URL được lưu trước vào bộ nhớ đệm.

Mã như sau trong phiên bản 2:

const manifestEntries = await workboxBuild.getFileManifestEntries({...});

có thể được viết lại trong v3 như sau:

const {manifestEntries, count, size, warnings} = await workboxBuild.getManifest({...});

// Use manifestEntries like before.
// Optionally, log the new info returned in count, size, warnings.
  • Xoá hàm generateFileManifest(). Thay vào đó, nhà phát triển nên gọi getManifest() và sử dụng phản hồi của lệnh này để ghi dữ liệu vào ổ đĩa ở định dạng phù hợp.

hộp-máy-tính-hết hạn-bộ nhớ đệm

  • API trình bổ trợ vẫn không thay đổi, đây là chế độ mà hầu hết các nhà phát triển sẽ sử dụng. Tuy nhiên, có những thay đổi đáng kể về API ảnh hưởng đến những nhà phát triển sử dụng API này dưới dạng một lớp độc lập. Tham khảo tài liệu này để biết giao diện API đã cập nhật.

workbox-cli

Nhà phát triển có thể chạy CLI với cờ --help cho toàn bộ các tham số được hỗ trợ.

  • Chúng tôi đã ngừng hỗ trợ bí danh workbox-cli của tập lệnh nhị phân. Tệp nhị phân hiện chỉ có thể truy cập dưới dạng workbox.
  • Các lệnh generate:sw và inject:manifest trong v2 đã được đổi tên thành generateSW và injectManifest trong v3.
  • Trong phiên bản 2, tệp cấu hình mặc định (dùng khi không được cung cấp rõ ràng) được giả định là workbox-cli-config.js trong thư mục hiện tại. Ở phiên bản 3, đó là workbox-config.js.

Kết hợp với nhau, điều này có nghĩa là trong phiên bản 2:

$ workbox inject:manifest

sẽ chạy quy trình xây dựng "chèn tệp kê khai", sử dụng cấu hình được đọc từ workbox-cli-config.js và trong phiên bản 3:

$ workbox injectManifest

sẽ làm tương tự, nhưng đọc cấu hình từ workbox-config.js.

lưu trước hộp làm việc

  • Phương thức precache() trước đây đã thực hiện cả việc sửa đổi bộ nhớ đệm và thiết lập việc định tuyến để phân phát các mục nhập đã lưu vào bộ nhớ đệm. Hiện tại, precache() chỉ sửa đổi các mục trong bộ nhớ đệm và một phương thức mới, addRoute(), đã xuất hiện để đăng ký một tuyến nhằm phân phát những phản hồi được lưu vào bộ nhớ đệm đó. Các nhà phát triển muốn sử dụng chức năng hai trong một trước đây có thể chuyển sang gọi precacheAndRoute().
  • Một số tuỳ chọn trước đây được định cấu hình thông qua hàm khởi tạo WorkboxSW, giờ đây đã được truyền vào dưới dạng tham số options trong workbox.precaching.precacheAndRoute([...], options). Các giá trị mặc định cho các tuỳ chọn đó (khi không được định cấu hình) được liệt kê trong tài liệu tham khảo.
  • Theo mặc định, những URL không có đuôi tệp sẽ tự động được kiểm tra để đảm bảo so khớp với một mục trong bộ nhớ đệm có chứa đuôi tệp .html. Ví dụ: nếu một yêu cầu được thực hiện cho /path/to/index (không được lưu trước vào bộ nhớ đệm) và một mục được lưu trước vào bộ nhớ đệm cho /path/to/index.html, thì mục nhập được lưu trước vào bộ nhớ đệm đó sẽ được sử dụng. Nhà phát triển có thể vô hiệu hoá hành vi mới này bằng cách thiết lập {cleanUrls: false} khi truyền tuỳ chọn vào workbox.precaching.precacheAndRoute().
  • workbox-broadcast-update sẽ không còn tự động được định cấu hình để thông báo về các bản cập nhật bộ nhớ đệm cho các tài sản được lưu trước vào bộ nhớ đệm.

Mã sau trong phiên bản 2:

const workboxSW = new self.WorkboxSW({
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
  precacheChannelName: 'precache-updates',
});
workboxSW.precache([...]);

có phiên bản v3 tương đương với:

workbox.precaching.addPlugins([
    new workbox.broadcastUpdate.Plugin('precache-updates')
]);

workbox.precaching.precacheAndRoute([...], {
  cleanUrls: false,
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
});

định tuyến hộp công việc

  • Các nhà phát triển từng sử dụng workbox-routing qua không gian tên workbox.router.* của đối tượng WorkboxSW cần chuyển sang không gian tên mới workbox.routing.*.
  • Các tuyến đường hiện được đánh giá theo thứ tự người đăng ký lần đầu thắng. Đây là thứ tự ngược lại của đánh giá Route đã được sử dụng trong phiên bản 2, trong đó Route đăng ký gần đây nhất sẽ được ưu tiên.
  • Lớp ExpressRoute và tính năng hỗ trợ cho ký tự đại diện "Kiểu biểu thức" đã bị xoá. Điều này giúp giảm đáng kể kích thước của workbox-routing. Giờ đây, các chuỗi dùng làm tham số đầu tiên cho workbox.routing.registerRoute() sẽ được coi là khớp chính xác. Kết quả khớp ký tự đại diện hoặc một phần sẽ do RegExp xử lý – việc sử dụng bất kỳ RegExp nào khớp với một phần hoặc toàn bộ URL yêu cầu có thể kích hoạt một tuyến.
  • Xoá phương thức trợ giúp addFetchListener() của lớp Router. Nhà phát triển có thể thêm trình xử lý fetch của riêng mình một cách rõ ràng hoặc sử dụng giao diện do workbox.routing cung cấp để ngầm tạo trình xử lý fetch cho họ.
  • Phương thức registerRoutes() và unregisterRoutes() đã bị xoá. Phiên bản của các phương thức hoạt động trên một Route không bị thay đổi. Thay vào đó, các nhà phát triển cần đăng ký hoặc huỷ đăng ký nhiều tuyến cùng một lúc sẽ thực hiện một loạt lệnh gọi đến registerRoute() hoặc unregisterRoute().

Mã sau trong phiên bản 2:

const workboxSW = new self.WorkboxSW();

workboxSW.router.registerRoute(
  '/path/with/.*/wildcard/',
  workboxSW.strategies.staleWhileRevalidate()
);

workboxSW.router.registerRoute(
  new RegExp('^https://example.com/'),
  workboxSW.strategies.networkFirst()
);

có phiên bản v3 tương đương với:

workbox.routing.registerRoute(
  new RegExp('^https://example.com/'),
  workbox.strategies.networkFirst()
);

workbox.routing.registerRoute(
  new RegExp('^/path/with/.*/wildcard'),
  workbox.strategies.staleWhileRevalidate()
);

chiến lược hộp làm việc (trước đây gọi là Workbox-runtime-lưu vào bộ nhớ đệm)

  • Mô-đun workbox-runtime-caching hiện có tên chính thức là workbox-strategies và được phát hành trên npm dưới tên mới.
  • Việc sử dụng thời gian hết hạn của bộ nhớ đệm trong một chiến lược mà không cung cấp tên bộ nhớ đệm sẽ không còn hợp lệ. Trong phiên bản 2, bạn có thể:
workboxSW.strategies.staleWhileRevalidate({
  cacheExpiration: {maxEntries: 50},
});

Điều này sẽ dẫn đến việc các mục nhập hết hạn trong bộ nhớ đệm mặc định (điều này ngoài dự kiến). Trong phiên bản 3, tên bộ nhớ đệm là bắt buộc:

workboxSW.strategies.staleWhileRevalidate({
  cacheName: 'my-cache',
  plugins: [new workbox.expiration.Plugin({maxEntries: 50})],
});
  • Phương thức vòng đời cacheWillMatch được đổi tên thành cachedResponseWillBeUsed. Các nhà phát triển không nên thay đổi trạng thái này, trừ phi họ tự viết các trình bổ trợ tương ứng với cacheWillMatch.
  • Cú pháp để xác định trình bổ trợ khi định cấu hình chiến lược đã thay đổi. Bạn cần liệt kê rõ ràng từng trình bổ trợ trong thuộc tính plugins của cấu hình của chiến lược.

Mã sau trong phiên bản 2:

const workboxSW = new self.WorkboxSW();

const networkFirstStrategy = workboxSW.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  cacheExpiration: {
    maxEntries: 50,
  },
  cacheableResponse: {
    statuses: [0, 200],
  },
});

có phiên bản v3 tương đương với:

const networkFirstStrategy = workbox.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  plugins: [
    new workbox.expiration.Plugin({maxEntries: 50}),
    new workbox.cacheableResponse.Plugin({statuses: [0, 200]}),
  ],
});

Bạn có thể tìm hiểu thêm trong hướng dẫn "Sử dụng trình bổ trợ".

hộp làm việc sw

  • Về sau, workbox-sw đã được viết lại thành giao diện "trình tải" nhẹ, sử dụng một số cấu hình cơ bản và chịu trách nhiệm kéo các mô-đun khác cần thiết trong thời gian chạy. Thay vì tạo một thực thể mới của lớp WorkboxSW, nhà phát triển sẽ tương tác với một thực thể hiện có tự động hiển thị trong không gian tên chung.

Trước đây trong phiên bản 2:

importScripts('<path to workbox-sw>/importScripts/workbox-sw.prod.v2.1.3.js');

const workbox = new WorkboxSW({
  skipWaiting: true,
  clientsClaim: true,
  // etc.
});

workbox.router.registerRoute(...);

Trong phiên bản 3, bạn chỉ cần nhập tập lệnh workbox-sw.js và một phiên bản sẵn sàng sử dụng sẽ tự động có trong không gian tên chung dưới dạng workbox:

importScripts('<path to workbox-sw>/3.0.0/workbox-sw.js');

// workbox is implicitly created and ready for use.
workbox.routing.registerRoute(...);
  • skipWaiting và clientsClaim không còn là các tuỳ chọn được truyền đến hàm khởi tạo WorkboxSW. Thay vào đó, chúng đã được thay đổi thành các phương thức workbox.clientsClaim() và workbox.skipWaiting().
  • Tuỳ chọn handleFetch đã được hỗ trợ trước đây trong hàm khởi tạo v2 không còn được hỗ trợ trong v3. Các nhà phát triển cần chức năng tương tự để kiểm tra trình chạy dịch vụ mà không gọi bất kỳ trình xử lý tìm nạp nào có thể sử dụng tuỳ chọn "Bỏ qua cho mạng" có trong Công cụ dành cho nhà phát triển của Chrome.
Tuỳ chọn Bỏ qua cho mạng trong Công cụ của Chrome cho nhà phát triển.

trình bổ trợ web-pack-workbox

Trình bổ trợ này đã được viết lại đáng kể, và trong nhiều trường hợp, có thể được sử dụng ở chế độ "cấu hình không" (zero-cấu hình). Tham khảo tài liệu này để biết giao diện API đã cập nhật.

  • API này hiện hiển thị 2 lớp là GenerateSW và InjectManifest. Điều này giúp việc chuyển đổi giữa các chế độ trở nên rõ ràng so với hành vi của phiên bản 2, trong đó hành vi thay đổi dựa trên sự hiện diện của swSrc.
  • Theo mặc định, các tài sản trong quy trình biên dịch gói web sẽ được lưu trước vào bộ nhớ đệm và bạn không cần phải định cấu hình globPatterns nữa. Lý do duy nhất để tiếp tục sử dụng globPatterns là nếu bạn cần lưu trước các tài sản không có trong bản dựng gói web của mình vào bộ nhớ đệm. Nhìn chung, khi di chuyển sang trình bổ trợ v3, bạn nên bắt đầu bằng cách xoá tất cả cấu hình dựa trên glob trước đó và chỉ thêm lại nếu thực sự cần thiết.

Nhận trợ giúp

Chúng tôi dự kiến rằng hầu hết quá trình di chuyển sẽ đơn giản. Nếu bạn gặp phải các vấn đề không có trong hướng dẫn này, hãy cho chúng tôi biết bằng cách mở vấn đề trên GitHub.