Китайская версия интерфейса командной строки Workbox

При написании приложения PWA я использовал инструмент WorkBox.Во время использования я обнаружил, что нет китайского справочного документа.Чтобы иметь лучший опыт и облегчить просмотр себе и другим, я перевел его здесь.workbox-cli.

Что такое интерфейс командной строки Workbox?

Командная строка рабочего ящика (вworkbox-cliпакет) поworkboxОн состоит из программы NodeJS, которая может работать в Windows, Mac и UNIX-подобных средах.workbox-cliсодержитworkbox-buildмодуль и обеспечивает простой способ интеграции Workbox в процесс сборки командной строки с гибкой конфигурацией.

Установить интерфейс командной строки

Установить этот CLI так же просто, как запустить следующую команду в терминале.

NPM:

$ npm install workbox-cli --global

YARN:

$ yarn global add workbox-cli

режим командной строки

CLI имеет 4 разных режима:

wizard: Шаг за мастер для установки Workbox для вашего проекта.
generateSW: создание полного сервисного работника.
injectManifest: вложите ресурсы в ваш проектprecacheсередина.
copyLibraries: Скопируйте библиотеку Workbox в указанный каталог.

wizard

Рабочий ящикwizardОн задаст вам ряд вопросов о вашем локальном каталоге установки и о том, какие файлы вы хотите предварительно кэшировать. Ваш ответ сгенерирует файл конфигурации дляgenerateSWиспользуется режим.

Большинство разработчиков запустят его только один раз.workbox wizard, вы можете вручную изменить сгенерированный init файл конфигурации, используя любой из параметров, поддерживаемых конфигурацией сборки.

использоватьwizard:

$ workbox wizard

generateSW

Вы можете использовать интерфейс командной строки Workbox для создания рабочих процессов с полным набором услуг через файл конфигурации (например, черезwizardделать файлы).

Просто запустите следующую команду:

$ workbox generateSW path/to/config.js

Встроенные в Workbox функции предварительного кэширования и кэширования во время выполнения избавляют от необходимости вручную настраивать поведение своих сервис-воркеров.generateSWмодель.

:white_check_mark: когда использоватьgenerateSW

Вы хотите предварительно кэшировать файлы.
Вам нужна простая конфигурация времени выполнения (например, конфигурация позволяет вам определять маршруты и политики).

:x: когда не использоватьgenerateSW

Вы хотите использовать некоторые другие функции Service Worker.
Вы хотите импортировать другие сценарии или добавить другую логику.

injectManifest

Для разработчиков, которым нужен больший контроль над окончательным сгенерированным файлом сервис-воркера, используйтеinjectManifestмодель. Для этого режима требуется, чтобы у вас был существующий файл сервис-воркера (расположение файла вconfig.jsуказано в).

бегатьworkbox injectManifest, он будет искать указанную строку в исходном файле сервис-воркера (по умолчаниюprecaching.precacheAndRoute([]). Он заменяет пустой массив списком предварительно кэшированных URL-адресов и записывает сервис-воркер вconfig.jsЦелевое расположение, указанное в элементе конфигурации. Остальной код в исходном файле сервисного работника остается прежним.

Его можно использовать следующим образом:

$ workbox injectManifest path/to/config.js

:white_check_mark: когда использоватьinjectManifest

Вам нужен больший контроль над сервис-воркером.
Вы хотите предварительно кэшировать файлы.
Существуют более сложные требования с точки зрения маршрутизации.
Вы хотите использовать сервисный работник с другими API (например, Web Push).

:x: когда не использоватьinjectManifest

Вам нужен самый простой способ разместить сервис-воркеров на вашем сайте.

copyLibraries

если вы хотите использоватьinjectManifestрежим и хотите разместить библиотеку Workbox в своем собственном источнике вместо CDN Workbox, тогда этот режим полезен.

При запуске просто укажите путь записи:

$ workbox copyLibraries third_party/workbox/

Интеграция процесса сборки

Почему Workbox необходимо интегрировать с моим процессом сборки?

Проект Workbox содержит необходимые библиотеки, которые вместе предоставляют возможности сервисного работника вашего веб-приложения. Чтобы эффективно использовать эти библиотеки, Workbox необходимо интегрировать в процесс сборки вашего веб-приложения. Убедитесь, что ваш сервисный работник может эффективно предварительно кэшировать весь критический контент в вашем веб-приложении и поддерживать актуальность данных контента.

во время сборки`workbox-cli`Это правильный выбор?

Если ваш текущий процесс сборки основан на сценариях npm, тоworkbox-cliхороший выбор.

Если вы в настоящее время используете Webpack в качестве инструмента сборки, используйтеworkbox-webback-pluginэто лучший выбор.

Если вы в настоящее время используетеGulp,GruntИли какие-то другие инструменты, построенные на Node.js, то несколько процентовworkbox-buildв ваш скрипт сборки - хороший вариант.

Если у вас нет процесса сборки, вам нужно выбрать его, прежде чем выполнять предварительную обработку рабочей области. Имейте в виду, что запуск рабочей области вручную может привести к некоторым ошибкам, если вы забудете запустить ее и посетители увидят старый контент.

Установить и настроить

Пучокworkbox-cliПосле того, как вы установили зависимости для разработки вашего проекта, вы можете добавить вызов workbox в конец сценария npm существующего процесса сборки:

пакет.json:

{
  "scripts": {
    "build": "my-build-script && workbox <mode> <path/to/config.js>"
  }
}

использоватьgenerateSWилиinjectManifest(в зависимости от того, как вы его используете), чтобы заменить<mode>, замените на путь к вашему конфигурационному файлу<path/to/config.js>. Ваш файл конфигурации может бытьworkbox wizardСоздайте или настройте вручную.

настроить

`generateSW`Используемые элементы конфигурации

НижеgenerateSWСписок используемых элементов конфигурации.

importWorkboxFrom

необязательный,String,По умолчаниюcdn.

Допустимые значения:cdn,local,disabled.

cdn: по умолчанию используйте CDN Workbox в Google Cloud Storage.
local: Скопируйте все библиотеки времени выполнения Workbox в каталог версий сервис-воркера, затем настройте сервис-воркер на использование этих файлов. Этот вариант предназначен для разработчиков, которые хотят самостоятельно разместить все свое внутреннее пространство, а не полагаться на CDN Google Cloud Storage.
disabled: откажется от автоматического поведения. Вы можете разместить локальную копию библиотеки Workbox по предпочитаемому URL-адресу и передатьimportScriptsЭлемент конфигурации передает правильный путь кworkbox-sw.js.
Примечание. В WebPack он также поддерживает строку, соответствующую имени блока WebPack, содержащему пользовательский пакет библиотеки времени выполнения Workbox.

пример

importWorkboxFrom: 'local'

skipWaiting

необязательный,Boolean,По умолчаниюfalse.

Следует ли пропустить сервисного работникаwaitingэтап жизненного цикла, обычно связанный сclientsClaim: trueиспользовать вместе.

пример

skipWaiting: true

clientsClaim

необязательный,Boolean,По умолчаниюfalse.

работник службы вactiveДолжен ли он начать управлять любыми существующими клиентами сразу после активации.

пример:

clientsClaim: true

runtimeCaching

необязательный,ObjectизArray,По умолчанию[].

проходя вurlPatterns,handlersи некоторые доступныеoptions, в сгенерированном сервис-воркере, чтобы добавить соответствующий код для обработки кеша во время выполнения.

По умолчаниюglobPatternsПолучите предварительно кэшированный URL-запрос, вводить его не нужно.runtimeCachingсередина.

handlerЗначение соответствуетworkbox.strategiesПоддерживаемые имена политик.

Свойство options настраивает истечение срока действия кэша, кэшированные ответы и подключаемые модули обновления широковещательного кэша для данного экземпляра маршрута.

пример

runtimeCaching: [{
    // 匹配包含`api`的任何同源请求。
    urlPattern: /api/,
    // 应用网络优先策略。
    handler: 'networkFirst',
    options: {
      // 超过10s使用缓存做为回退方案。
      networkTimeoutSeconds: 10,
      // 为此路由指定自定义缓存名称。
      cacheName: 'my-api-cache',
      // 配置自定义缓存过期。
      expiration: {
        maxEntries: 5,
        maxAgeSeconds: 60,
      },
      // 配置background sync.
      backgroundSync: {
        name: 'my-queue-name',
        options: {
          maxRetentionTime: 60 * 60,
        },
      },
      // 配置哪些response是可缓存的。
      cacheableResponse: {
        statuses: [0, 200],
        headers: {'x-test': 'true'},
      },
      // 配置广播缓存更新插件。
      broadcastUpdate: {
        channelName: 'my-update-channel',
      },
      // 添加您需要的任何其他逻辑插件。
      plugins: [
        {cacheDidUpdate: () => /* 自定义插件代码 */}
      ],
      // matchOptions 和 fetchOptions 用于配置 handler.
      fetchOptions: {
        mode: 'no-cors',
      },
      matchOptions: {
        ignoreSearch: true,
      },
    },
  }, {
    // 匹配跨域请求，使用以origin开头的正则:
    urlPattern: new RegExp('^https://cors\.example\.com/'),
    handler: 'staleWhileRevalidate',
    options: {
      cacheableResponse: {
        statuses: [0, 200]
      }
    }
  }]

navigateFallback

необязательный,String,По умолчаниюundefined.

для созданияNavigationRoute, ответ не кэшируетсяnavigation requestsURL.

Он подходит для общих запросов HTML-навигации App Shell в сценариях SPA.

Он не подходит для использования в качестве запасного варианта, когда браузер находится в автономном режиме.

пример

navigateFallback: '/app-shell'

navigateFallbackBlacklist

необязательный,Array of RegExp,По умолчанию[].

Необязательный массив регулярных выражений для ограничения настроенногоnavigateFallbackПрименимые URL-адреса.

Это полезно, если только часть URL-адресов вашего веб-сайта считается частью SPA.

Если оба настроеныnavigateFallbackBlacklistа такжеnavigateFallbackWhitelist,ноnavigateFallbackBlacklistприоритет.

пример

// 以`/_`开头或包含`admin`的URL，加入黑名单
navigateFallbackBlacklist: [/^\/_/, /admin/]

navigateFallbackWhitelist

необязательный,Array of RegExp,По умолчанию[].

Необязательный массив регулярных выражений для ограничения настроенногоnavigateFallbackПрименимые URL-адреса.

Это полезно, если только часть URL-адресов вашего веб-сайта считается частью SPA.

Если оба настроеныnavigateFallbackBlacklistа такжеnavigateFallbackWhitelist,ноnavigateFallbackBlacklistприоритет.

// 以`/pages`开头的URL加入白名单
navigateFallbackWhitelist: [/^\/pages/]

importScripts

требуется,Array of String.

передается сгенерированному сервис-воркеруimportScripts()Массив JS-файлов.

Если один из импортированных файловself .__ precacheManifestпеременная установлена вManifestEntrysмассив, записи в массиве будут автоматически предварительно кэшироваться при порождении сервисного работника.

Это также полезно, когда вы хотите, чтобы Workbox создал рабочий файл службы верхнего уровня, но хотите включить некоторый дополнительный код (например, прослушиватели событий для push).

пример

importScripts: ['push-notifications.abcd1234.js']

ignoreUrlParametersMatching

необязательный,Array of RegExp,По умолчанию[/^utm_/].

Любое регулярное выражение, соответствующее этому массиву, будет удалено перед поиском предварительно кэшированного совпадения.

Эта функция полезна, если ваш пользовательский запрос содержит адреса параметров URL, используемые для подсчета источников трафика.

пример

// 它会忽略所有参数
ignoreUrlParametersMatching: [/./]

directoryIndex

необязательный,String,По умолчаниюindex.html.

Если с/Конечный URL-адрес не соответствует предварительно кэшированному URL-адресу для запроса, тогда это значение будет добавлено к URL-адресу и будет проверено на совпадение с предварительно кэшированным.

Вы должны настроить все, что использует ваш сервер, например индексы каталогов.

Например

directoryIndex: 'index.html'

cacheId

необязательный,String,По умолчаниюnull.

Необязательный идентификатор имени, используемого кэшем Workbox.

В основном используется для локальной разработки, может быть загружен с того жеhttp:// localhost:portИсточник предоставляет несколько сайтов.

пример

cacheId: 'my-app'

offlineGoogleAnalytics

необязательный,Boolean,По умолчаниюfalse.

Контролирует, включать лиoffline Google Analyticsслужба поддержки.

`injectManifest`Используемые элементы конфигурации

НижеinjectManifestЭлемент конфигурации, используемый командой.

swSrc

требуется,String.

Помимо содержанияinjectPointRegexp, путь к исходному файлу сервис-воркера содержит пользовательский код.

Среда узла: Ваш файл сервис-воркера должен содержать правильныйworkbox.precachingВызов метода, используемого для внедрения манифеста предварительного кэша.

Среда веб-пакета: Ваш файл сервис-воркера должен ссылатьсяself .__ precacheManifestпеременная, получить скомпилированныйManifestEntrysСписок:workbox.precaching.precacheAndRoute(self.__precacheManifest)

пример

swDest: path.join('src', 'sw.js')

injectionPointRegexp

необязательный,RegExp,По умолчанию/(\.precacheAndRoute\()\s*\[\s*\]\s*(\))/.

По умолчанию используетсяRegExpбудетswSrcстрока найдена в файлеprecacheAndRoute([]), и воля[]Массив заменяется предварительно кэшированнымManifestEntrysмассив .

Если вы хотитеManifestEntrysвводить вswSrcдругое расположение файла, настройте его так, чтобы он содержал разныеRegExp. Массив манифеста будет вставлен между группами захвата.

пример

// 将清单注入到变量赋值中
injectionPointRegexp: new RegExp('(const myManifest =)(;)')

Элементы конфигурации, используемые обоими

Следующие параметры используются обеими командами.

swDest

требуется,String.

Путь и имя файла сервисного работника, созданного в процессе сборки. В узле это будет относительно текущего рабочего каталога. В веб-пакете это будет относительно выходного каталога веб-пакета.

пример

swDest: path.join('dist', 'sw.js')

globDirectory

необязательный,String,По умолчаниюundefined.

вы хотите соответствоватьglobPatternsБазовый каталог относительно текущего рабочего каталога.

Если это установлено, обязательно настройтеglobPatternsпункт.

пример

// 所有模式相对于当前目录
globDirectory: '.'

globFollow

необязательный,Boolean,По умолчаниюtrue.

Обязательно следуйте символическим ссылкам при создании манифеста предварительного кэша.

Для получения дополнительной информации см.глобус документацияизfollow.

пример

globFollow: false

globIgnores

необязательный,Array of String,По умолчанию['node_modules/**/*'].

Шаблоны, соответствующие файлам, всегда исключаются при создании предварительного кэша.

Для получения дополнительной информации см.глобус документацияизignore.

пример

globIgnores: ['**/ignored.html']

globPatterns

необязательный,Array of String,По умолчанию['**/*.{js,css,html}'](для сборки рабочего ящика) или[](для плагина workbox-webpack).

Любые файлы, соответствующие этим шаблонам, будут включены в манифест предварительного кэширования.

Для получения дополнительной информации см.глобус документация.

Уведомление:использоватьworkbox-webpack-pluginОбычно не нужно устанавливатьglobPatterns, который по умолчанию автоматически предварительно кэширует файлы для конвейера сборки webpack. При использовании плагина веб-пакета вам нужно только установить ресурсы, не относящиеся к веб-пакету, которые необходимо кэшировать.

пример

globPatterns: ['dist/*.{js,png,html,css}']

globStrict

необязательный,Boolean,По умолчаниюtrue.

еслиtrue, сборка завершится ошибкой, если возникнет ошибка при создании манифеста предварительного кэша. еслиfalse, соответствующий файл будет пропущен.

Для получения дополнительной информации см.глобус документацияизstrict.

templatedUrls

опционально, сStringилиArrayизObject, По умолчаниюnull.

Если URL-адрес создается на основе логики на стороне сервера, его содержимое может зависеть от нескольких файлов или какого-либо другого уникального строкового значения.

При использовании со строковыми массивами они будут интерпретироваться какglobшаблон, а содержимое любого файла, соответствующего шаблону, будет использоваться для создания уникальной версии URL.

Если используется с одной строкой, она будет интерпретироваться как уникальная информация о версии, сгенерированная вашим заданным URL-адресом.

Например

templatedUrls: {
  '/app-shell': [
    'dev/templates/app-shell.hbs',
    'dev/**/*.css',
    ],
  '/other-page': 'my-version-info',
}

maximumFileSizeToCacheInBytes

необязательный,Number,По умолчанию2097152.

Это значение можно использовать для определения максимального размера предварительно кэшированных файлов. Запретить предварительное кэширование очень больших файлов.

пример

// 限制最大4MB
maximumFileSizeToCacheInBytes: 4 * 1024 * 1024

dontCacheBustUrlsMatching

необязательный,RegExp,По умолчаниюnull.

Предполагается, что ресурсы, соответствующие этому регулярному выражению, имеют уникальную версию по их URL-адресу, и при предварительном кэшировании избегается обычная очистка кеша HTTP.

Хотя это и не требуется, рекомендуется, если существующий процесс сборки уже вставляет[hash]значение, аRegExpдля обнаружения этих значений, поскольку это уменьшает объем пропускной способности, потребляемой при предварительном кэшировании.

пример

dontCacheBustUrlsMatching: /\.\w{8}\./

modifyUrlPrefix

необязательный,Stringобъект, по умолчаниюnull.

Карта префиксов, если она присутствует в манифесте предварительного кэша, запись будет заменена соответствующим значением.

Например, если настройки вашего веб-узла не соответствуют настройкам вашей локальной файловой системы, вы можете использовать этот параметр, чтобы удалить или добавить префиксы пути из записей манифеста.

В качестве альтернативы с большей гибкостью вы можете использоватьmanifestTransformsи предоставьте функцию, которая изменяет запись в манифесте, используя любую предоставленную вами логику.

пример

modifyUrlPrefix: {
  // 从URL中删除'/ dist'前缀
  '/dist': ''
}

manifestTransforms

необязательный,Array of ManifestTransform,По умолчаниюnull.

один или большеManifestTransformФункция, применяемая к сгенерированному последовательному листингу.

Если также указаноmodifyUrlPrefixилиdontCacheBustUrlsMatching, сначала будет применено соответствующее преобразование.

пример

manifestTransforms: [
  // 删除某些URL的基本转换
  (originalManifest) => {
    const manifest = originalManifest.filter(
      (entry) => entry.url !== 'ignored.html');
    // 可选，设置警告消息。
    const warnings = []; 
    return {manifest, warnings};
  }
]

Название блога:Блог Ван Лепина

Адрес блога CSDN:blog.csdn.net/lecepin

В этой работе используетсяCreative Commons Attribution-NonCommercial-No Derivatives 4.0 Международная лицензияЛицензия.

Что такое интерфейс командной строки Workbox?

Установить интерфейс командной строки

режим командной строки

wizard

generateSW

injectManifest

copyLibraries

Интеграция процесса сборки

Почему Workbox необходимо интегрировать с моим процессом сборки?

во время сборкиworkbox-cliЭто правильный выбор?

Установить и настроить

настроить

generateSWИспользуемые элементы конфигурации

importWorkboxFrom

skipWaiting

clientsClaim

runtimeCaching

navigateFallback

navigateFallbackBlacklist

navigateFallbackWhitelist

importScripts

ignoreUrlParametersMatching

directoryIndex

cacheId

offlineGoogleAnalytics

injectManifestИспользуемые элементы конфигурации

swSrc

injectionPointRegexp

Элементы конфигурации, используемые обоими

swDest

globDirectory

globFollow

globIgnores

globPatterns

globStrict

templatedUrls

maximumFileSizeToCacheInBytes

dontCacheBustUrlsMatching

modifyUrlPrefix

manifestTransforms

во время сборки`workbox-cli`Это правильный выбор?

`generateSW`Используемые элементы конфигурации

`injectManifest`Используемые элементы конфигурации