ปลั๊กอิน Workbox-webpack

Workbox มีปลั๊กอิน Webpack จำนวน 2 ปลั๊กอิน โดยปลั๊กอินหนึ่งจะสร้าง Service Worker ที่สมบูรณ์ให้คุณ และอีกปลั๊กอินหนึ่งที่จะสร้างรายการเนื้อหาเพื่อแคชล่วงหน้าที่จะแทรกลงในไฟล์ Service Worker

ปลั๊กอินติดตั้งใช้งานเป็น 2 คลาสในโมดูล workbox-webpack-plugin ที่มีชื่อว่า GenerateSW และ InjectManifest คำตอบของคําถามต่อไปนี้จะช่วยคุณเลือกปลั๊กอินและการกำหนดค่าที่เหมาะสม

ปลั๊กอินที่ควรใช้

GenerateSW

ปลั๊กอิน GenerateSW จะสร้างไฟล์ Service Worker ให้คุณและเพิ่มลงในไปป์ไลน์ชิ้นงาน webpack

กรณีที่ควรใช้ GenerateSW

  • คุณต้องการแคชไฟล์ไว้ล่วงหน้า
  • คุณต้องใช้แคชรันไทม์แบบง่าย

ไม่ควรใช้ GenerateSW เมื่อใด

  • คุณต้องการใช้ฟีเจอร์อื่นๆ ของ Service Worker (เช่น Web Push)
  • คุณต้องการนําเข้าสคริปต์เพิ่มเติม หรือเพิ่มตรรกะเพิ่มเติมสําหรับกลยุทธ์การแคชที่กําหนดเอง

InjectManifest

ปลั๊กอิน InjectManifest จะสร้างรายการ URL ที่จะแคชล่วงหน้าและเพิ่มไฟล์ Manifest แคชล่วงหน้านั้นลงในไฟล์ Service Worker ที่มีอยู่ มิเช่นนั้นระบบจะปล่อยไฟล์ไว้เหมือนเดิม

กรณีที่ควรใช้ InjectManifest

  • คุณต้องการควบคุม Service Worker ได้มากขึ้น
  • คุณต้องการแคชไฟล์ไว้ล่วงหน้า
  • คุณต้องปรับแต่งการกำหนดเส้นทางและกลยุทธ์
  • คุณต้องการใช้ Service Worker กับฟีเจอร์อื่นๆ ของแพลตฟอร์ม (เช่น Web Push)

ไม่ควรใช้ InjectManifest เมื่อใด

  • คุณต้องการวิธีที่ง่ายที่สุดในการเพิ่ม Service Worker ลงในเว็บไซต์

ปลั๊กอิน GenerateSW

คุณสามารถเพิ่มปลั๊กอิน GenerateSW ลงในการกำหนดค่า webpack ได้โดยทำดังนี้

// Inside of webpack.config.js:
const {GenerateSW} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new GenerateSW({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      navigateFallback: '...',
      runtimeCaching: [{
        // Routing via a matchCallback function:
        urlPattern: ({request, url}) => ...,
        handler: '...',
        options: {
          cacheName: '...',
          expiration: {
            maxEntries: ...,
          },
        },
      }, {
        // Routing via a RegExp:
        urlPattern: new RegExp('...'),
        handler: '...',
        options: {
          cacheName: '...',
          plugins: [..., ...],
        },
      }],
      skipWaiting: ...,
    }),
  ],
};

ซึ่งจะสร้าง Service Worker ที่มีการตั้งค่าการแคชล่วงหน้าสำหรับชิ้นงาน webpack ทั้งหมดที่การกําหนดค่าของคุณเลือกไว้ และกฎการแคชรันไทม์ที่ระบุ

ดูตัวเลือกการกําหนดค่าชุดสมบูรณ์ได้ในเอกสารอ้างอิง

InjectManifest ปลั๊กอิน

คุณสามารถเพิ่มปลั๊กอิน InjectManifest ลงในการกำหนดค่า webpack ได้โดยทำดังนี้

// Inside of webpack.config.js:
const {InjectManifest} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new InjectManifest({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      swSrc: '...',
    }),
  ],
};

ซึ่งจะสร้างไฟล์ Manifest สำหรับการแคชล่วงหน้าโดยอิงตามชิ้นงาน webpack ที่การกําหนดค่าของคุณเลือกไว้ และแทรกลงในไฟล์ Service Worker ที่คอมไพล์และรวมไว้แล้ว

ดูตัวเลือกการกำหนดค่าทั้งชุดได้ในเอกสารประกอบอ้างอิง

ข้อมูลเพิ่มเติม

ดูคําแนะนําเกี่ยวกับการใช้ปลั๊กอินในบริบทของบิลด์ webpack ขนาดใหญ่ได้ในส่วน "Progressive Web Application" ของเอกสารประกอบ webpack

ประเภท

GenerateSW

คลาสนี้รองรับการสร้างไฟล์ Service Worker ใหม่ที่ใช้ได้ทันที ซึ่งเป็นส่วนหนึ่งของกระบวนการคอมไพล์ webpack

ใช้อินสแตนซ์ของ GenerateSW ในอาร์เรย์ plugins ของการกำหนดค่า Webpack

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new GenerateSW({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  navigateFallback: '...',
  runtimeCaching: [{
    // Routing via a matchCallback function:
    urlPattern: ({request, url}) => ...,
    handler: '...',
    options: {
      cacheName: '...',
      expiration: {
        maxEntries: ...,
      },
    },
  }, {
    // Routing via a RegExp:
    urlPattern: new RegExp('...'),
    handler: '...',
    options: {
      cacheName: '...',
      plugins: [..., ...],
    },
  }],
  skipWaiting: ...,
});

พร็อพเพอร์ตี้

  • constructor

    โมฆะ

    สร้างอินสแตนซ์ของ GenerateSW

    ฟังก์ชัน constructor มีรูปแบบดังนี้ 

    (config?: GenerateSWConfig) => {...}

    • การกำหนดค่า

      GenerateSWConfig ไม่บังคับ

  • การกำหนดค่า

    GenerateSWConfig

GenerateSWConfig

พร็อพเพอร์ตี้

  • additionalManifestEntries

    (string | ManifestEntry)[] ไม่บังคับ

    รายการรายการที่จะแคชไว้ล่วงหน้า นอกเหนือจากรายการที่สร้างขึ้นเป็นส่วนหนึ่งของการกำหนดค่าบิลด์

  • babelPresetEnvTargets

    string[] ไม่บังคับ

    ค่าเริ่มต้นคือ ["chrome >= 56"]

    เป้าหมายที่จะส่งให้กับ babel-preset-env เมื่อแปลงไฟล์ Service Worker Bundle

  • cacheId

    สตริง ไม่บังคับ

    รหัสที่ไม่บังคับที่จะใส่ไว้ก่อนชื่อแคช การดำเนินการนี้มีประโยชน์อย่างยิ่งสําหรับการพัฒนาในเครื่องซึ่งอาจมีการแสดงเว็บไซต์หลายแห่งจากhttp://localhost:portต้นทางเดียวกัน

  • ชิ้นส่วน

    string[] ไม่บังคับ

    ชื่อกลุ่มอย่างน้อย 1 รายการที่ควรรวมไฟล์เอาต์พุตที่เกี่ยวข้องไว้ในไฟล์ Manifest สำหรับการแคชล่วงหน้า

  • cleanupOutdatedCaches

    บูลีน ไม่บังคับ

    ค่าเริ่มต้นคือ false

    ระบุว่า Workbox ควรพยายามระบุและลบแคชล่วงหน้าที่สร้างขึ้นโดยเวอร์ชันเก่าที่เข้ากันไม่ได้หรือไม่

  • clientsClaim

    บูลีน ไม่บังคับ

    ค่าเริ่มต้นคือ false

    กำหนดว่า Service Worker ควรเริ่มควบคุมไคลเอ็นต์ที่มีอยู่ทันทีที่เปิดใช้งานหรือไม่

  • directoryIndex

    สตริง ไม่บังคับ

    หากคำขอไปยัง URL ที่ลงท้ายด้วย / ไม่ตรงกับ URL ที่แคชไว้ล่วงหน้า ระบบจะเพิ่มค่านี้ต่อท้าย URL แล้วตรวจสอบการจับคู่กับแคชล่วงหน้า ค่านี้ควรตั้งค่าเป็นค่าที่เว็บเซิร์ฟเวอร์ใช้สำหรับดัชนีไดเรกทอรี

  • disableDevLogs

    บูลีน ไม่บังคับ

    ค่าเริ่มต้นคือ false

  • dontCacheBustURLsMatching

    RegExp ไม่บังคับ

    ระบบจะถือว่าชิ้นงานที่ตรงกับค่านี้มีเวอร์ชันที่ไม่ซ้ำกันผ่าน URL และยกเว้นจากการป้องกันแคช HTTP ปกติที่ดำเนินการเมื่อป้อนข้อมูลแคชล่วงหน้า แม้ว่าจะไม่บังคับ แต่เราขอแนะนำให้คุณระบุนิพจน์ทั่วไปที่จะตรวจหาค่า [hash] ในชื่อไฟล์แต่ละรายการ หากกระบวนการสร้างที่มีอยู่แทรกค่า [hash] ไว้ในชื่อไฟล์แต่ละรายการอยู่แล้ว เนื่องจากจะช่วยประหยัดแบนด์วิดท์ที่ใช้เมื่อแคชล่วงหน้า

  • ยกเว้น

    (สตริง | นิพจน์ทั่วไป | ฟังก์ชัน)[] ไม่บังคับ

    ตัวระบุอย่างน้อย 1 รายการที่ใช้ยกเว้นเนื้อหาจากไฟล์ Manifest สำหรับการแคชล่วงหน้า ระบบจะตีความตามกฎเดียวกันกับตัวเลือก exclude มาตรฐานของ webpack หากไม่ได้ระบุ ค่าเริ่มต้นจะเป็น [/\.map$/, /^manifest.*\.js$]

  • excludeChunks

    string[] ไม่บังคับ

    ชื่อกลุ่มอย่างน้อย 1 รายการที่ควรยกเว้นไฟล์เอาต์พุตที่เกี่ยวข้องจากไฟล์ Manifest สำหรับการแคชล่วงหน้า

  • ignoreURLParametersMatching

    RegExp[] ไม่บังคับ

    ระบบจะนำชื่อพารามิเตอร์การค้นหาที่ตรงกับนิพจน์ทั่วไปรายการใดรายการหนึ่งในอาร์เรย์นี้ออกก่อนที่จะมองหาการจับคู่การแคชล่วงหน้า ซึ่งจะมีประโยชน์ในกรณีที่ผู้ใช้อาจขอ URL ที่มีพารามิเตอร์ของ URL ที่ใช้ติดตามแหล่งที่มาของการเข้าชม หากไม่ได้ระบุ ค่าเริ่มต้นจะเป็น [/^utm_/, /^fbclid$/]

  • importScripts

    string[] ไม่บังคับ

    รายการไฟล์ JavaScript ที่ควรส่งไปยัง importScripts() ภายในไฟล์ Service Worker ที่สร้างขึ้น ซึ่งจะมีประโยชน์เมื่อคุณต้องการให้ Workbox สร้างไฟล์ Service Worker ระดับบนสุด แต่ต้องการรวมโค้ดเพิ่มเติม เช่น โปรแกรมรับฟังเหตุการณ์ Push

  • importScriptsViaChunks

    string[] ไม่บังคับ

    ชื่อของกลุ่ม webpack อย่างน้อย 1 รายการ เนื้อหาของข้อมูลโค้ดเหล่านั้นจะรวมอยู่ใน Service Worker ที่สร้างขึ้นผ่านการเรียกใช้ importScripts()

  • รวม

    (string | RegExp | function)[] ไม่บังคับ

    ตัวระบุอย่างน้อย 1 รายการที่ใช้ใส่เนื้อหาในไฟล์ Manifest ของแคชล่วงหน้า ระบบจะตีความตามกฎเดียวกันกับตัวเลือก include มาตรฐานของ webpack

  • inlineWorkboxRuntime

    บูลีน ไม่บังคับ

    ค่าเริ่มต้นคือ false

    ระบุว่าควรรวมโค้ดรันไทม์สำหรับไลบรารี Workbox ไว้ใน Service Worker ระดับบนสุด หรือแยกเป็นไฟล์แยกต่างหากที่ต้องนำไปใช้งานควบคู่ไปกับ Service Worker การแยกรันไทม์หมายความว่าผู้ใช้ไม่จำเป็นต้องดาวน์โหลดโค้ด Workbox ซ้ำทุกครั้งที่มีการเปลี่ยนแปลง Service Worker ระดับบนสุด

  • manifestEntries

    ManifestEntry[] ไม่บังคับ

  • manifestTransforms

    ManifestTransform[] ไม่บังคับ

    ฟังก์ชันอย่างน้อย 1 รายการที่จะนําไปใช้กับไฟล์ Manifest ที่สร้างขึ้นตามลําดับ หากระบุ modifyURLPrefix หรือ dontCacheBustURLsMatching ด้วย ระบบจะใช้การเปลี่ยนรูปแบบที่เกี่ยวข้องก่อน

  • maximumFileSizeToCacheInBytes

    ตัวเลข ไม่บังคับ

    ค่าเริ่มต้นคือ 2097152

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

  • โหมด

    สตริง ไม่บังคับ

    หากตั้งค่าเป็น "production" ระบบจะสร้าง Service Worker Bundle ที่เพิ่มประสิทธิภาพซึ่งไม่รวมข้อมูลการแก้ไขข้อบกพร่อง หากไม่ได้กําหนดค่าอย่างชัดเจนที่นี่ ระบบจะใช้ค่า mode ที่กําหนดค่าไว้ในการคอมไพล์ webpack ปัจจุบัน

  • modifyURLPrefix

    ออบเจ็กต์ ไม่บังคับ

    สตริงการแมปออบเจ็กต์จะใส่คำนำหน้าสตริงค่าการแทนที่ เพื่อนำมาใช้ เช่น นำคำนำหน้าเส้นทางออกหรือเพิ่มคำนำหน้าเส้นทางจากรายการไฟล์ Manifest หากการตั้งค่าเว็บโฮสติ้งไม่ตรงกับการตั้งค่าระบบไฟล์ในเครื่อง ทั้งนี้เป็นทางเลือกที่มีความยืดหยุ่นมากขึ้น คุณสามารถใช้ตัวเลือก manifestTransforms และให้ฟังก์ชันที่แก้ไขรายการในไฟล์ Manifest โดยใช้ตรรกะที่คุณระบุ

    ตัวอย่างการใช้งาน

    // Replace a '/dist/' prefix with '/', and also prepend
// '/static' to every URL.
modifyURLPrefix: {
  '/dist/': '/',
  '': '/static',
}
  • navigateFallback

    สตริง ไม่บังคับ

    ค่าเริ่มต้นคือ null

    หากระบุไว้ คำขอไปยังส่วนต่างๆ ทั้งหมดสำหรับ URL ที่ไม่ได้แคชไว้ล่วงหน้าจะได้รับการตอบสนองด้วย HTML ที่ URL ที่ระบุ คุณต้องส่ง URL ของเอกสาร HTML ที่แสดงในไฟล์ Manifest สำหรับการแคชล่วงหน้า ตัวเลือกนี้มีไว้สำหรับใช้ในสถานการณ์แอปหน้าเดียว ซึ่งคุณต้องการให้การนำทางทั้งหมดใช้ App Shell HTML เดียวกัน

  • navigateFallbackAllowlist

    RegExp[] ไม่บังคับ

    อาร์เรย์นิพจน์ทั่วไปที่ไม่บังคับซึ่งจํากัด URL ที่ลักษณะการทํางาน navigateFallback ที่กําหนดค่าไว้มีผล วิธีนี้มีประโยชน์หากควรถือว่า URL ของเว็บไซต์เพียงส่วนหนึ่งส่วนใดเป็นส่วนหนึ่งของแอปหน้าเดียว หากมีการกำหนดค่าทั้ง navigateFallbackDenylist และ navigateFallbackAllowlist ไว้ รายการที่ไม่อนุญาตจะมีผลก่อน

    หมายเหตุ: ระบบอาจประเมินนิพจน์ทั่วไปเหล่านี้กับ URL ปลายทางทุกรายการในระหว่างการนําทาง หลีกเลี่ยงการใช้ RegExps ซับซ้อน ไม่เช่นนั้นผู้ใช้อาจเห็นความล่าช้าเมื่อไปยังส่วนต่างๆ ของเว็บไซต์

  • navigateFallbackDenylist

    RegExp[] ไม่บังคับ

    อาร์เรย์นิพจน์ทั่วไปที่ไม่บังคับซึ่งจํากัด URL ที่ลักษณะการทํางาน navigateFallback ที่กําหนดค่าไว้มีผล ซึ่งจะมีประโยชน์ในกรณีที่ควรถือว่า URL ของเว็บไซต์เพียงบางส่วนเป็นส่วนหนึ่งของแอปหน้าเว็บเดียวเท่านั้น หากกําหนดค่าทั้ง navigateFallbackDenylist และ navigateFallbackAllowlist ไว้ รายการที่ปฏิเสธจะมีลําดับความสําคัญเหนือกว่า

    หมายเหตุ: ระบบอาจประเมินนิพจน์ทั่วไปเหล่านี้กับ URL ปลายทางทุกรายการในระหว่างการนําทาง หลีกเลี่ยงการใช้ RegExps ซับซ้อน ไม่เช่นนั้นผู้ใช้อาจเห็นความล่าช้าเมื่อไปยังส่วนต่างๆ ของเว็บไซต์

  • navigationPreload

    บูลีน ไม่บังคับ

    ค่าเริ่มต้นคือ false

    การเปิดใช้การโหลดนำทางล่วงหน้าใน Service Worker ที่สร้างขึ้นหรือไม่ เมื่อตั้งค่าเป็น "จริง" คุณต้องใส่ runtimeCaching เพื่อตั้งค่ากลยุทธ์การตอบกลับที่เหมาะสมซึ่งจะจับคู่กับคำขอการนําทาง และใช้การตอบกลับที่โหลดไว้ล่วงหน้า

  • offlineGoogleAnalytics

    บูลีน | GoogleAnalyticsInitializeOptions ไม่บังคับ

    ค่าเริ่มต้นคือ false

    ควบคุมว่าจะรวมการรองรับ Google Analytics ออฟไลน์ หรือไม่ เมื่อ true ระบบจะเพิ่มการเรียก initialize() ของ workbox-google-analytics ลงใน Service Worker ที่สร้างขึ้น เมื่อตั้งค่าเป็น Object ระบบจะส่งออบเจ็กต์นั้นไปยังการเรียก initialize() ซึ่งจะช่วยให้คุณปรับแต่งลักษณะการทํางานได้

  • runtimeCaching

    RuntimeCaching[] ไม่บังคับ

    เมื่อใช้เครื่องมือสร้างของ Workbox เพื่อสร้าง Service Worker คุณจะระบุการกำหนดค่าการแคชรันไทม์ได้อย่างน้อย 1 รายการ จากนั้นระบบจะแปลเป็นคําเรียก workbox-routing.registerRoute โดยใช้การกําหนดค่าการจับคู่และตัวแฮนเดิลที่คุณกําหนด

    โปรดดูตัวเลือกทั้งหมดในเอกสารของ workbox-build.RuntimeCaching ตัวอย่างด้านล่างแสดงการกำหนดค่าโดยทั่วไปซึ่งมีการกำหนดเส้นทางรันไทม์ 2 เส้นทาง

  • skipWaiting

    บูลีน ไม่บังคับ

    ค่าเริ่มต้นคือ false

    เพิ่มการเรียก skipWaiting() แบบไม่มีเงื่อนไขไปยัง Service Worker ที่สร้างขึ้นหรือไม่ หากเป็น false ระบบจะเพิ่ม message Listener แทน ซึ่งจะช่วยให้หน้าไคลเอ็นต์ทริกเกอร์ skipWaiting() ได้โดยเรียกใช้ postMessage({type: 'SKIP_WAITING'}) ใน Service Worker ที่รออยู่

  • sourcemap

    บูลีน ไม่บังคับ

    ค่าเริ่มต้นคือ true

    การสร้าง Sourcemap สําหรับไฟล์ Service Worker ที่สร้างขึ้น

  • swDest

    string ไม่บังคับ

    ค่าเริ่มต้นคือ "service-worker.js"

    ชื่อเนื้อหาของไฟล์ Service Worker ที่สร้างโดยปลั๊กอินนี้

InjectManifest

คลาสนี้รองรับการคอมไพล์ไฟล์ Service Worker ที่ให้ไว้ผ่าน swSrc และแทรกรายการ URL และข้อมูลการแก้ไขสำหรับการแคชล่วงหน้าตามไปป์ไลน์เนื้อหาของ Webpack ลงในโปรแกรมทำงานของบริการ

ใช้อินสแตนซ์ของ InjectManifest ในอาร์เรย์ plugins ของการกำหนดค่า webpack

นอกจากการแทรกไฟล์ Manifest แล้ว ปลั๊กอินนี้จะทำการคอมไพล์ไฟล์ swSrc โดยใช้ตัวเลือกจากการกําหนดค่า webpack หลัก

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new InjectManifest({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  swSrc: '...',
});

พร็อพเพอร์ตี้

พร็อพเพอร์ตี้

default

ประเภท

ออบเจ็กต์

พร็อพเพอร์ตี้

  • GenerateSW

    query

  • InjectManifest

    query