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 việc thay đổi có thể gây lỗi được giới thiệu trong Workbox phiên bản 3, với các ví dụ về những thay đổi bạn cần thực hiện khi nâng cấp từ quá trình thiết lập Workbox v2.

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

Nền phiên bản 3

Bản phát hành phiên bản 3 của Workbox cho thấy quá trình 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 Hộp làm việc. Lượng mã thời gian chạy của trình chạy dịch vụ được tải xuống và thực thi đã giảm. Thay vì chọn dùng một gói nguyên khối cho mọi người, chỉ mã cho những tính năng mà bạn đang sử dụng mới được nhập 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 các thư viện thời gian chạy của Workbox, giúp bạn thiết lập và chạy Workbox dễ dàng hơn.
  • Gỡ lỗi và ghi nhật ký tốt hơn. Trải nghiệm gỡ lỗi và ghi nhật ký đã được cải thiện đáng kể. Nhật ký gỡ lỗi được bật theo mặc định bất cứ khi nào Workbox được sử dụng từ nguồn gốc localhost, đồng thời tất cả 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ợ webpack 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 webpack, cho phép trường hợp sử dụng cấu hình không được thiết lập (zero-config) khi bạn muốn lưu trước tất cả thành phần trong quy trình tạo bản 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 đó có vẻ khó xử lý hoặc gây ra tình trạng phản mẫu, yêu cầu 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 đây ả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 có chung một tập hợp tuỳ chọn cấu hình phổ biến.

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

workbox-background-sync

  • 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, phải được truyề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 đây, tệp này đã được chuyển vào dưới dạng thuộc tính của các lựa chọn.) Tham khảo tài liệu về 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 truyề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 v2, bạn 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 về giao diện API đã cập nhật.

workbox-build

  • 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 (sẽ đi theo đường liên kết tượng trưng) và strict: true (ít chấp nhận lỗi "bất thường"). Bạn có thể tắt một trong hai rồi quay lại hành vi trước đó bằng cách đặt 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 các phản hồi mà hàm này trả về. Một số trường hợp được coi là lỗi nghiêm trọng trong phiên bản 2 hiện được cho phép, nhưng được báo cáo qua warnings (một mảng chuỗi).

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

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, nhưng 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 các 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 thêm một thuộc tính warnings không bắt buộc. Đó phải là một mảng thông tin chứa cảnh báo không nghiêm trọng.

Nếu bạn đang viết một ManifestTransform tuỳ chỉnh trong phiên bản 2, hãy viết mã như:

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ó 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 trong 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 thành:

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

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

workbox-cache-expiration

  • 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, 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 như một lớp độc lập. Tham khảo tài liệu về giao diện API đã cập nhật.

workbox-cli

Nhà phát triển có thể chạy giao diện dòng lệnh (CLI) bằng cờ --help để có đủ bộ tham số được hỗ trợ.

  • Chúng tôi không còn hỗ trợ bí danh workbox-cli cho tập lệnh nhị phân. Giờ đây, bạn chỉ có thể truy cập tệp nhị phân dưới dạng workbox.
  • Các lệnh v2 generate:sw và inject:manifest đã đượ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. Trong phiên bản 3, đó là workbox-config.js.

Khi xem xét chung, điều này có nghĩa là trong phiên bản 2:

$ workbox inject:manifest

sẽ chạy "inject manifest" quy trình xây dựng, 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ữ hộp công việc

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

Mã sau đây trong phiên bản 2:

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

có 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 làm việc

  • Những 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 là workbox.routing.*.
  • Các tuyến đường hiện được đánh giá theo thứ tự đăng ký thắng lần đầu. Đây là thứ tự ngược lại của phép đánh giá Route được dùng trong phiên bản 2, trong đó Route được đăng ký gần đây nhất sẽ được ưu tiên.
  • Lớp ExpressRoute và hỗ trợ cho "Express-style" ký tự đại diện đã bị xoá. Thao tác này sẽ 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à kết quả khớp chính xác. Các kết quả khớp với ký tự đại diện hoặc một phần sẽ được RegExp xử lý. Việc sử dụng RegExp bất kỳ khớp với một phần hoặc toàn bộ URL yêu cầu đều có thể kích hoạt một tuyến.
  • Phương thức trợ giúp addFetchListener() của lớp Router đã bị xoá. Các nhà phát triển có thể thêm rõ ràng trình xử lý fetch của riêng mình hoặc sử dụng giao diện do workbox.routing cung cấp. Giao diện này sẽ ngầm tạo trình xử lý fetch cho họ.
  • Đã xoá các phương thức registerRoutes() và unregisterRoutes(). Phiên bản của những phương thức hoạt động trên một Route không thay đổi và các nhà phát triển cần đăng ký hoặc huỷ đăng ký nhiều tuyến cùng lúc nên thực hiện một loạt lệnh gọi đến registerRoute() hoặc unregisterRoute().

Mã sau đây 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ó 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()
);

các chiến lược hộp công việc (trước đây gọi là lưu vào bộ nhớ đệm hộp công việc-thời gian chạy)

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

Điều này sẽ dẫn đến các mục nhập hết hạn trong bộ nhớ đệm mặc định – đây là điều 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 thấy thay đổi này, trừ phi họ viết các trình bổ trợ của riêng họ để phản ứng với cacheWillMatch.
  • Cú pháp để chỉ định trình bổ trợ khi định cấu hình một chiến lược đã thay đổi. Bạn cần liệt kê rõ ràng mỗi trình bổ trợ trong thuộc tính plugins của cấu hình chiến lược.

Mã sau đây 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ó 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 phần "Sử dụng trình bổ trợ" của chúng tôi.

hộp-công-việc

  • Tính năng nâng cao, workbox-sw đã được viết lại thành một "trình tải" nhẹ nhận được một số cấu hình cơ bản và chịu trách nhiệm lấy 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ó được tự động hiển thị trong không gian tên chung.

Trước đó 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 xuất hiện 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à tuỳ chọn được truyền đến hàm khởi tạo WorkboxSW nữa. Thay vào đó, các phương thức này đã được thay đổi thành các phương thức workbox.clientsClaim() và workbox.skipWaiting().
  • Tuỳ chọn handleFetch từng được hỗ trợ trong hàm khởi tạo v2 không còn được hỗ trợ trong v3 nữa. Các nhà phát triển cần có chức năng tương tự để kiểm thử trình chạy dịch vụ mà không cần gọi bất kỳ trình xử lý tìm nạp nào có thể sử dụng tính năng "Bỏ qua cho mạng" có sẵn 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.

workbox-webpack-plugin

Trình bổ trợ này đã được viết lại đáng kể và trong nhiều trường hợp, có thể được dùng trong "cấu hình không" . Tham khảo tài liệu về 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 làm cho việc chuyển đổi giữa các chế độ trở nên rõ ràng, so với hành vi v2 trong đó hành vi thay đổi dựa trên sự hiện diện của swSrc.
  • Theo mặc định, các thành phần trong quy trình biên dịch webpack sẽ được lưu trước vào bộ nhớ đệm và không cần thiết 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 những tài sản không có trong bản dựng webpack của mình vào bộ nhớ đệm. Nhìn chung, khi 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.

Nhận trợ giúp

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