ย้ายข้อมูลจาก Workbox v2 ไปยัง v3

คู่มือนี้เน้นเรื่องการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นของ Workbox v3 และมีตัวอย่างการเปลี่ยนแปลงที่คุณจำเป็นต้องทำเมื่ออัปเกรดจากการตั้งค่า Workbox v2

หากคุณกำลังใช้ชุดค่าผสม sw-precache/sw-toolbox เดิมและต้องการเปลี่ยนไปใช้ Workbox เป็นครั้งแรก โปรดดูคำแนะนำในการย้ายข้อมูลอื่นซึ่งจะช่วยได้

พื้นหลัง v3

รุ่น Workbox v3 แสดงถึงการเปลี่ยนโครงสร้างโค้ดฐานของโค้ดที่มีอยู่อย่างมีนัยสำคัญ เป้าหมายโดยรวมมีดังนี้

• ลดขนาดของ Workbox ลดจำนวนโค้ดรันไทม์ของ Service Worker ที่ดาวน์โหลดและเรียกใช้แล้ว ระบบจะนำเข้าเฉพาะโค้ดสำหรับฟีเจอร์ที่คุณใช้อยู่ขณะรันไทม์เท่านั้น แทนที่จะเลือกให้ทุกคนเข้าร่วมแพ็กเกจแบบโมโนลิธ
• พื้นที่ทำงานมี CDN เรามีการโฮสต์ CDN ที่อิงตาม Google Cloud Storage ที่รองรับอย่างเต็มรูปแบบเป็นตัวเลือก Canonical สำหรับการเข้าถึงไลบรารีรันไทม์ของ Workbox ทำให้เริ่มต้นใช้งานและทำงานกับ Workbox ได้ง่ายขึ้น
• การแก้ไขข้อบกพร่องและบันทึกที่ดียิ่งขึ้น ประสบการณ์การแก้ไขข้อบกพร่องและการบันทึกได้รับการปรับปรุงอย่างมาก บันทึกการแก้ไขข้อบกพร่องเปิดใช้อยู่โดยค่าเริ่มต้นเมื่อมีการใช้ Workbox จากต้นทาง localhost รวมถึงจะตัดการบันทึกและการยืนยันทั้งหมดออกจากบิลด์ที่ใช้งานจริง
• ปลั๊กอิน Webpack ที่ดียิ่งขึ้น workbox-webpack-plugin ผสานรวมอย่างใกล้ชิดกับกระบวนการบิลด์ Webpack มากขึ้น ทำให้ใช้ Use Case ที่ไม่มีการกำหนดค่าได้เมื่อคุณต้องการแคชเนื้อหาทั้งหมดล่วงหน้าในไปป์ไลน์บิลด์

การบรรลุเป้าหมายเหล่านี้ พร้อมปรับปรุงอินเทอร์เฟซก่อนหน้านี้บางส่วนที่ทำให้รู้สึกอึดอัดใจหรือนำไปสู่รูปแบบที่ไม่เหมือนเดิม จะต้องมีการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในรุ่น v3

การเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบ

การกำหนดค่าบิวด์

การเปลี่ยนแปลงต่อไปนี้ส่งผลกระทบต่อลักษณะการทำงานของเครื่องมือบิลด์ทั้งหมด (workbox-build, workbox-cli, workbox-webpack-plugin) ซึ่งใช้ชุดตัวเลือกการกำหนดค่าร่วมกัน

• ชื่อตัวแฮนเดิล 'fastest' ก่อนหน้านี้ถูกต้องและถือเป็นชื่อแทนของ 'staleWhileRevalidate' เมื่อกำหนดค่า runtimeCaching ซึ่งจะใช้ไม่ได้อีกต่อไป และนักพัฒนาแอปควรเปลี่ยนไปใช้ 'staleWhileRevalidate' โดยตรง
• มีการอัปเดตชื่อพร็อพเพอร์ตี้ runtimeCaching.options หลายรายการและมีการตรวจสอบพารามิเตอร์เพิ่มเติม ซึ่งจะทำให้บิลด์ล้มเหลวหากใช้การกำหนดค่าที่ไม่ถูกต้อง ดูเอกสารประกอบของ runtimeCaching เพื่อดูรายการตัวเลือกที่รองรับในปัจจุบัน

การซิงค์เบื้องหลัง

• ขณะนี้พารามิเตอร์การกำหนดค่า maxRetentionTime จะได้รับการแปลค่าเป็นจำนวนนาที แทนที่จะเป็นจำนวนมิลลิวินาที
• ตอนนี้มีสตริงที่จำเป็นซึ่งแสดงชื่อคิว ซึ่งต้องส่งผ่านเป็นพารามิเตอร์แรกเมื่อสร้างคลาสปลั๊กอินหรือสแตนด์อโลน (ก่อนหน้านี้มีการส่งเป็นพร็อพเพอร์ตี้ของตัวเลือก) โปรดดูข้อมูลเกี่ยวกับแพลตฟอร์ม API ที่อัปเดตแล้วในเอกสารประกอบ

workbox-broadcast-cache-update

• ตอนนี้จะมีสตริงที่ต้องระบุซึ่งแสดงชื่อช่อง ซึ่งจะต้องส่งเป็นพารามิเตอร์แรกเมื่อสร้างคลาสปลั๊กอินหรือสแตนด์อโลน

ตัวอย่างเช่น ใน v2 คุณจะเริ่มต้นคลาสปลั๊กอินดังนี้:

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

การใช้งานที่เทียบเท่าใน v3 คือ:

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

โปรดดูข้อมูลเกี่ยวกับแพลตฟอร์ม API ที่อัปเดตแล้วในเอกสารประกอบ

การสร้างกล่องงาน

• โดยค่าเริ่มต้น การจับคู่รูปแบบ glob จะทำงานโดยมีตัวเลือก follow: true (ซึ่งจะอยู่หลังลิงก์สัญลักษณ์) และ strict: true (ซึ่งยอมรับข้อผิดพลาด "ผิดปกติ") น้อยกว่า) คุณปิดใช้ตัวเลือกหนึ่งและกลับไปยังลักษณะการทำงานก่อนหน้าได้โดยการตั้งค่า globFollow: false และ/หรือ globStrict: false ในการกำหนดค่าบิลด์
• ฟังก์ชันใน workbox-build ทั้งหมดจะแสดงผลพร็อพเพอร์ตี้เพิ่มเติม warnings ในการตอบสนองที่แสดงผล ตอนนี้ระบบอนุญาตบางสถานการณ์ที่ถือว่าเป็นข้อผิดพลาดร้ายแรงใน v2 แล้ว แต่รายงานผ่าน warnings ซึ่งเป็นอาร์เรย์ของสตริง

ใน v2 คุณอาจเรียก generateSW เช่น

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}`));

แม้ว่าคุณจะสามารถใช้โค้ดเดียวกันใน v3 แต่คุณควรตรวจหา warnings และบันทึก:

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}`));

• นักพัฒนาซอฟต์แวร์ที่เขียนฟังก์ชัน ManifestTransform ที่กำหนดเองของตนใน v2 จำเป็นต้องแสดงผลอาร์เรย์ไฟล์ Manifest ในออบเจ็กต์ (กล่าวคือ แทนที่จะใช้ return manifestArray; คุณควรใช้ return {manifest: manifestArray};) วิธีนี้จะช่วยให้ปลั๊กอินของคุณรวมพร็อพเพอร์ตี้ warnings ที่ไม่บังคับได้ ซึ่งควรเป็นอาร์เรย์ของสตริงที่มีข้อมูลคำเตือนที่ไม่ร้ายแรง

หากคุณเขียน ManifestTransform ที่กำหนดเองใน v2 ให้ใช้โค้ดอย่างเช่น

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

มีค่าเทียบเท่า v3 กับ:

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: []};
};

• ฟังก์ชัน getFileManifestEntries() ได้เปลี่ยนชื่อเป็น getManifest() แล้ว และขณะนี้สัญญาการแสดงผลจะมีข้อมูลเพิ่มเติมเกี่ยวกับ URL ที่จัดเก็บในแคชล่วงหน้า

โค้ดที่มีลักษณะดังนี้ใน v2:

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

สามารถเขียนใหม่ใน v3 เป็น:

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

// Use manifestEntries like before.
// Optionally, log the new info returned in count, size, warnings.

• ฟังก์ชัน generateFileManifest() ถูกนำออกแล้ว เราแนะนำให้นักพัฒนาซอฟต์แวร์เรียกใช้ getManifest() แทน และใช้การตอบสนองเพื่อเขียนข้อมูลลงในดิสก์ในรูปแบบที่เหมาะสม

การหมดอายุของแคชเวิร์กบ็อกซ์

• API ปลั๊กอินจะยังคงเหมือนเดิม ซึ่งเป็นโหมดที่นักพัฒนาซอฟต์แวร์ส่วนใหญ่จะใช้งาน อย่างไรก็ตาม มีการเปลี่ยนแปลง API ที่สำคัญซึ่งส่งผลต่อนักพัฒนาซอฟต์แวร์ที่ใช้คลาสแบบสแตนด์อโลน โปรดดูข้อมูลเกี่ยวกับแพลตฟอร์ม API ที่อัปเดตแล้วในเอกสารประกอบ

workbox-cli

นักพัฒนาแอปสามารถเรียกใช้ CLI ด้วยแฟล็ก --help สำหรับพารามิเตอร์ที่รองรับทั้งชุด

• การสนับสนุนชื่อแทน workbox-cli สำหรับสคริปต์ไบนารีถูกนำออกแล้ว ตอนนี้คุณสามารถเข้าถึงไบนารีในฐานะ workbox เท่านั้น
• คำสั่ง v2 คือ generate:sw และ inject:manifest เปลี่ยนชื่อเป็น generateSW และ injectManifest ใน v3
• ใน v2 ระบบจะถือว่าไฟล์การกำหนดค่าเริ่มต้น (ใช้เมื่อไม่ได้ระบุไฟล์อย่างชัดเจน) เป็น workbox-cli-config.js ในไดเรกทอรีปัจจุบัน ใน v3 จะเป็น workbox-config.js

เมื่อนำมารวมกันแล้วหมายความว่าใน v2:

$ workbox inject:manifest

จะเรียกใช้กระบวนการบิลด์ "แทรกไฟล์ Manifest" โดยใช้การกำหนดค่าที่อ่านจาก workbox-cli-config.js และใน v3 ดังนี้

$ workbox injectManifest

จะดำเนินการเช่นเดียวกัน แต่จะอ่านการกำหนดค่าจาก workbox-config.js

การแคชเวิร์กบ็อกซ์

• ก่อนหน้านี้เมธอด precache() ได้ดำเนินการทั้งการแก้ไขแคชและตั้งค่าการกำหนดเส้นทางเพื่อแสดงรายการที่แคช ตอนนี้ precache() จะแก้ไขเฉพาะรายการแคช และเมธอด addRoute() ใหม่ ได้มีการเปิดเผยเพื่อลงทะเบียนเส้นทางที่จะแสดงการตอบกลับที่แคชไว้เหล่านั้น นักพัฒนาแอปที่ต้องการใช้ฟังก์ชันแบบ 2 อินวันก่อนหน้านี้สามารถเปลี่ยนไปใช้การเรียกใช้ precacheAndRoute() ได้
• ตอนนี้ตัวเลือกหลายรายการที่เคยกำหนดค่าผ่านตัวสร้าง WorkboxSW จะส่งเข้ามาเป็นพารามิเตอร์ options ใน workbox.precaching.precacheAndRoute([...], options) ค่าเริ่มต้นสำหรับตัวเลือกเหล่านั้นในกรณีที่ไม่ได้กำหนดค่าจะแสดงอยู่ในเอกสารอ้างอิง
• โดยค่าเริ่มต้น ระบบจะตรวจสอบ URL ที่ไม่มีนามสกุลไฟล์ว่าตรงกับรายการแคชที่มีนามสกุล .html โดยอัตโนมัติหรือไม่ เช่น หากมีคำขอสำหรับ /path/to/index (ซึ่งไม่แคชล่วงหน้า) และมีรายการที่จัดเก็บในแคชล่วงหน้าสำหรับ /path/to/index.html ระบบจะใช้รายการที่แคชไว้ล่วงหน้า นักพัฒนาซอฟต์แวร์ปิดใช้ลักษณะการทำงานใหม่นี้ได้โดยการตั้งค่า {cleanUrls: false} เมื่อส่งตัวเลือกไปยัง workbox.precaching.precacheAndRoute()
• จะไม่มีการกำหนดค่าให้ workbox-broadcast-update ประกาศการอัปเดตแคชโดยอัตโนมัติสำหรับเนื้อหาที่แคชไว้ล่วงหน้าอีกต่อไป

โค้ดต่อไปนี้ใน v2:

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

มีค่าเทียบเท่า v3 กับ:

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

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

การกำหนดเส้นทางพื้นที่ทำงาน

• นักพัฒนาซอฟต์แวร์ที่ใช้ workbox-routing ก่อนหน้านี้ผ่านเนมสเปซ workbox.router.* ของออบเจ็กต์ WorkboxSW ต้องเปลี่ยนไปใช้เนมสเปซใหม่ workbox.routing.*
• ตอนนี้เส้นทางจะได้รับการประเมินตามลำดับที่ได้ลงทะเบียนครั้งแรก นี่เป็นลำดับที่ตรงกันข้ามของการประเมิน Route ที่ใช้ใน v2 โดย Route ที่ลงทะเบียนล่าสุดจะมีความสำคัญเหนือกว่า
• คลาส ExpressRoute และการรองรับไวลด์การ์ด "สไตล์ด่วน" ถูกนำออกแล้ว ซึ่งจะลดขนาดของ workbox-routing ลงอย่างมาก ตอนนี้สตริงที่ใช้เป็นพารามิเตอร์แรกไปยัง workbox.routing.registerRoute() จะถือว่าเป็นการจับคู่ที่ตรงกันทั้งหมด RegExp ควรจัดการการจับคู่ไวลด์การ์ดหรือการจับคู่บางส่วน การใช้ RegExp ที่ตรงกับ URL คำขอบางส่วนหรือทั้งหมดจะทริกเกอร์เส้นทางได้
• นำเมธอดตัวช่วยaddFetchListener()ของคลาสRouterออกแล้ว นักพัฒนาซอฟต์แวร์จะเพิ่มเครื่องจัดการ fetch ของตนเองอย่างชัดแจ้ง หรือใช้อินเทอร์เฟซที่ workbox.routing มีให้ ซึ่งจะสร้างเครื่องจัดการ fetch ให้โดยปริยาย
• นำเมธอด registerRoutes() และ unregisterRoutes() ออกแล้ว เวอร์ชันของเมธอดต่างๆ ที่ทำงานใน Route เดียวจะไม่มีการเปลี่ยนแปลง และนักพัฒนาแอปที่ต้องลงทะเบียนหรือยกเลิกการลงทะเบียนหลายเส้นทางพร้อมกันควรสร้างการเรียกใช้หลายครั้งไปยัง registerRoute() หรือ unregisterRoute() แทน

โค้ดต่อไปนี้ใน v2:

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()
);

มีค่าเทียบเท่า v3 กับ:

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

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

Workbox-strategies (ก่อนหน้านี้เรียกว่า Workbox-runtime-caching)

• โมดูล workbox-runtime-caching มีชื่ออย่างเป็นทางการว่า workbox-strategies และได้เผยแพร่เมื่อวันที่ npm ภายใต้ชื่อใหม่
• การใช้การหมดอายุของแคชในกลยุทธ์โดยไม่ได้ระบุชื่อแคชจะใช้ไม่ได้อีกต่อไป ใน v2 เป็นไปได้ดังนี้

workboxSW.strategies.staleWhileRevalidate({
  cacheExpiration: {maxEntries: 50},
});

ซึ่งอาจทำให้รายการหมดอายุในแคชเริ่มต้น ซึ่งที่ไม่คาดคิด ใน V3 ต้องใช้ชื่อแคชดังนี้

workboxSW.strategies.staleWhileRevalidate({
  cacheName: 'my-cache',
  plugins: [new workbox.expiration.Plugin({maxEntries: 50})],
});

• เปลี่ยนชื่อวิธีการสำหรับวงจร cacheWillMatch เป็น cachedResponseWillBeUsed แล้ว ไม่ควรเห็นการเปลี่ยนแปลงนี้ของนักพัฒนาซอฟต์แวร์ เว้นแต่นักพัฒนาจะเขียนปลั๊กอินของตนเองที่ตอบสนองต่อ cacheWillMatch
• ไวยากรณ์สำหรับการระบุปลั๊กอินเมื่อกำหนดค่ากลยุทธ์มีการเปลี่ยนแปลง ปลั๊กอินแต่ละรายการต้องระบุไว้อย่างชัดเจนในพร็อพเพอร์ตี้ plugins ของการกำหนดค่าของกลยุทธ์

โค้ดต่อไปนี้ใน v2:

const workboxSW = new self.WorkboxSW();

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

มีค่าเทียบเท่า v3 กับ:

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

คุณสามารถเรียนรู้เพิ่มเติมได้ในคู่มือ "การใช้ปลั๊กอิน"

Workbox-SW

• ขั้นสูง มีการเขียน workbox-sw ใหม่เป็นอินเทอร์เฟซ "ตัวโหลด" ขนาดเล็ก ซึ่งต้องใช้การกำหนดค่าพื้นฐานและมีหน้าที่ดึงโมดูลอื่นๆ ที่จำเป็นในช่วงรันไทม์ แทนที่จะสร้างอินสแตนซ์ใหม่ของคลาส WorkboxSW นักพัฒนาซอฟต์แวร์จะโต้ตอบกับอินสแตนซ์ที่มีอยู่ซึ่งแสดงให้เห็นโดยอัตโนมัติในเนมสเปซส่วนกลาง

ก่อนหน้านี้ใน v2:

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(...);

ใน v3 คุณเพียงต้องนำเข้าสคริปต์ workbox-sw.js และอินสแตนซ์ที่พร้อมใช้งานจะพร้อมใช้งานในเนมสเปซสากลโดยอัตโนมัติเป็น workbox:

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

// workbox is implicitly created and ready for use.
workbox.routing.registerRoute(...);

• skipWaiting และ clientsClaim ไม่ใช่ตัวเลือกที่ส่งไปยังเครื่องมือสร้าง WorkboxSW อีกต่อไป แต่เปลี่ยนเป็นเมธอด workbox.clientsClaim() และ workbox.skipWaiting() แทน
• ตัวเลือก handleFetch ที่เคยสนับสนุนในเครื่องมือสร้าง v2 ไม่ได้รับการสนับสนุนใน v3 อีกต่อไป นักพัฒนาซอฟต์แวร์ที่ต้องการฟังก์ชันการทำงานที่คล้ายกันเพื่อทดสอบโปรแกรมทำงานของบริการโดยไม่มีการเรียกใช้เครื่องจัดการการดึงข้อมูลจะใช้ตัวเลือก "ข้ามเครือข่าย" ที่มีอยู่ในเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์ของ Chrome ได้

ปลั๊กอิน Workbox-webpack

ปลั๊กอินนี้ได้รับการเขียนใหม่อย่างมาก และในหลายๆ กรณีจะสามารถใช้ได้ในโหมด "การกำหนดค่าแบบเป็นศูนย์" โปรดดูข้อมูลเกี่ยวกับแพลตฟอร์ม API ที่อัปเดตแล้วในเอกสารประกอบ

• ขณะนี้ API ได้แสดง 2 คลาสแล้ว ได้แก่ GenerateSW และ InjectManifest ซึ่งทำให้มีการสลับโหมดอย่างชัดเจน เมื่อเทียบกับลักษณะการทำงานของ v2 ที่พฤติกรรมเปลี่ยนไปตามการมี swSrc
• โดยค่าเริ่มต้น ระบบจะจัดเก็บเนื้อหาในไปป์ไลน์การคอมไพล์ Webpack ไว้ในแคชล่วงหน้า และไม่จำเป็นต้องกำหนดค่า globPatterns อีกต่อไป เหตุผลเดียวที่จะใช้ globPatterns ต่อไปคือหากคุณต้องการแคชชิ้นงานที่ไม่ได้รวมไว้ในบิลด์ Webpack ล่วงหน้า โดยทั่วไปแล้วเมื่อย้ายข้อมูลไปยังปลั๊กอิน v3 คุณควรเริ่มต้นด้วยการนำการกำหนดค่าที่ใช้ glob ก่อนหน้านี้ออกทั้งหมด และเพิ่มกลับเข้าไปใหม่เมื่อจำเป็นเท่านั้น

การขอความช่วยเหลือ

เราคาดว่าการย้ายข้อมูลส่วนใหญ่จะตรงไปตรงมา หากพบปัญหาที่ไม่ได้กล่าวถึงในคู่มือนี้ โปรดแจ้งให้เราทราบโดยเปิดปัญหาใน GitHub