ปลั๊กอิน 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: ...,
});

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

  • เครื่องมือสร้าง

    void

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

    ฟังก์ชัน constructor มีลักษณะดังนี้ 

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

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

      GenerateSWConfig ไม่บังคับ

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

    GenerateSWConfig

GenerateSWConfig

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

  • additionalManifestEntries

    (สตริง | ไฟล์ Manifest)[] ไม่บังคับ

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

  • babelPresetEnvTargets

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

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

    เป้าหมายที่จะส่งต่อไปยัง babel-preset-env เมื่อแปลแพ็กเกจ Service Worker

  • cacheId

    string ไม่บังคับ

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

  • เป็นท่อน

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

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

  • cleanupOutdatedCaches

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

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

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

  • clientsClaim

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

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

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

  • directoryIndex

    string ไม่บังคับ

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

  • disableDevLogs

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

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

  • dontCacheBustURLsMatching

    นิพจน์ทั่วไป ไม่บังคับ

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

  • ไม่รวม

    (สตริง | RegExp | function)[] ไม่บังคับ

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

  • excludeChunks

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

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

  • ignoreURLParametersMatching

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

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

  • importScripts

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

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

  • importScriptsViaChunks

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

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

  • รวม

    (สตริง | 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

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

  • โหมด

    string ไม่บังคับ

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

  • modifyURLPrefix

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

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

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

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

    string ไม่บังคับ

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

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

  • navigateFallbackAllowlist

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

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

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

  • navigateFallbackDenylist

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

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

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

  • 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 ระบบจะเพิ่ม Listener message แทน ซึ่งทำให้หน้าไคลเอ็นต์ทริกเกอร์ skipWaiting() โดยการเรียกใช้ postMessage({type: 'SKIP_WAITING'}) ในโปรแกรมทำงานของบริการรอ

  • การแมปแหล่งที่มา

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

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

    เลือกว่าจะสร้างการแมปแหล่งที่มาสำหรับไฟล์ 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: '...',
});

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

  • เครื่องมือสร้าง

    void

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

    ฟังก์ชัน constructor มีลักษณะดังนี้ 

    (config: WebpackInjectManifestOptions) => {...}

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

      WebpackInjectManifestOptions

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

    WebpackInjectManifestOptions

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

default

ประเภท

ออบเจ็กต์

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

  • GenerateSW

    query

  • InjectManifest

    query