คู่มือนี้เน้นเรื่องการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นของ 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