offline-plugin v 5.0.7

本插件旨在为webpack项目提供离线体验。它利用了ServiceWorker和AppCache作为后台备份。只需要在您的webpack.config.js中引入这个插件，并在客户端脚本中包含相应的runtime(运行时)。通过缓存所有(或部分) webpack输出的资源，您的项目就可以离线了。

安装

npm install offline-plugin [--save-dev]

设置

首先，在您的webpack.config.js中实例化插件。

var OfflinePlugin = require('offline-plugin');

module.exports = {
  // ...

  plugins: [
    // ... 其他插件
    // OfflinePlugin 是最后一个添加的比较好
    new OfflinePlugin()
  ]
  // ...
}

1
2
3
4
5
6
7
8
9
10
11
12

然后，将运行时(runtime)添加到入口文件(通常是主入口)：

require('offline-plugin/runtime').install();

ES6/Babel/TypeScript

import * as OfflinePluginRuntime from 'offline-plugin/runtime';
OfflinePluginRuntime.install();

1
2

下面示例展示如何设置配置项(TypeScript)：

import * as OfflinePluginRuntime from 'offline-plugin/runtime';

OfflinePluginRuntime.install({
  onUpdateReady: () => OfflinePluginRuntime.applyUpdate(),
  onUpdated: () => location.reload(),
});

1
2
3
4
5
6

如果你需要手动解决TypeScript定义文件，那么你可以添加这一行到你的ts文件:

/// <reference path="node_modules/offline-plugin/runtime.d.ts" />

文档

配置项(options)

这些配置项都是可选的，这里是默认设置

名称	类型	默认值	描述
appShell	`string`	null	以app shell model启动您的应用。可以设置为希望所有导航请求都返回的 HTML 文件。例如：`/app-shell.html`。后面会详述。
responseStrategy	`cache-first \| network-first`	`cache-first`	若设置为`cache-first`，则所有的请求均优先检查缓存，如果缓存是空的，则请求网络。若使用`network-first`，所有请求首先发送到网络，如果网络请求失败，则查询缓存作为回退。
externals	`Array<string>`	null	指定要缓存的其他(构建过程中的外部)URL. 例如：`['/static/img/media.png', 'https://fonts.googleapis.com/css?family=Roboto']`
excludes	`Array<string \| globs_pattern>`	`['*/.', '*/.map', '*/.gz']`	将哪些文件排除出缓存。以`.`开头和以`.map`或`.gz`为结尾的文件则被排除在外。 ⚠️注意：该项是在`rewrites`之前起作用的。
autoUpdate	`true \| number`	`false`	启用 ServiceWorker 和 AppCache 的自动更新。如果设置为`true`，则默认1小时间隔。我们可以传入数字来自定义更新间隔。请注意：如果用户在您的网站上打开了多个标签，那么更新可能发生的更频繁，因为每个打开的标签都有自己的更新间隔。示例：`true` 示例：`1000 * 60 * 60 * 5`(五小时)
relativePaths	`boolean`	`true`	当设置为`true`时，缓存中生成的所有路径是分别相对于 ServiceWorker 文件或 AppCache 文件夹位置。当设置了`publicPath`时，该项被忽略。而当该项设置为`true`时，则是`publicPath`被忽略。
rewrites	`Function \| Object`	Rewrite `/index.html` to `/`	提供一种更改加载资源URL的方式。当资源与客户期望有差异时，就需要它出场了。比方说CDN。后面会详述。
cacheMaps	`Array<Object>`		后面会详述。
ServiceWorker	`Object \| null \| false`		内容表格放不下，后面详述。
publicPath	`string`		和`webpack`的`output.publicPath`配置项类似。专门为 offline-plugin 指定或覆盖`publicPath`时非常有用。当未设置时，使用`webpack`的`output.publicPath`。当完全没有指定`publicPath`值时(无论是通过这个选项还是通过`webpack`的输出)，使用相对路径(参见`relativePaths`)。示例：`publicPath: /project/` 示例：`publicPath: 'https://example.com/project'`
version	`string \| (plugin: OfflinePlugin) => void`	当前时间和日期	缓存的版本。可以是函数，这在需要应用动态值的观察模式下非常有用。 · 若是函数，则在调用时将插件实例作为第一个参数。 · 若是字符串，可以插入`[hash]`标记。示例：`2018-6-20 09:53:56` 请注意如果您使用了默认值(date和time)，那么 service worker 的版本会在您每次构建项目时改变。
caches	`'all' \| Object`	`'all'`	允许您调整缓存资源的内容和方式. · `'all'`：意味着在外部配置项中列出的所有项目(所有`webpack`输出资产)和`URL`都将在安装时缓存。 · `Object`：对象有三个可能的`Array<string \| RegExp>`字段：`main`、`additional`、`optional`。所有的字段都是可选且默认为空的。更多内容后面详述。
AppCache	`Object \| null \| false`		设置`AppCache`缓存的设置。设置为`null`或`false`则禁用`AppCache`生成。更多内容后面详述。
updateStrategy	`'changed' \| 'all'`	`'changed'`	缓存更新策略。请不要更改此选项，除非您确信您知道自己在做什么。后面也有详述。

配置项详述部分

appShell: string

默认：null 示例："/"

在制作单页应用时，通常使用app shell model模式。

为了让offline-plugin将所有位置的导航请求重定向到特定的缓存，我们可以配置appShell项，比方说:appShell: '/'

SSR

当使用AppShell模型进行服务端渲染时，请确保不会缓存任何服务端渲染的数据。其中最简单的方法是创建一个没有任何服务端渲染数据的HTML文件路由并进行缓存。例如：appShell: '/app-shell.html'

Advanced

appShell是cacheMaps项为ServiceWorker准备的，而AppCache.FallBack则对应AppCache。

rewrites

该回调将迭代assets和由插件生成的serviceWorker文件中的external数组。这可以帮助开发人员根据场景修改资源，比如为多个资源设置多个 CDN。

rewrites: function(asset) {	
    if (asset.endsWith('html')) {
        return 'https://www.qq.com/' + asset;
    } else {
        return 'https://s1.url.cn/' + asset;
    }

    return asset;
}

1
2
3
4
5
6
7
8
9

cacheMaps

该项允许将请求重定向到缓存或另一个请求。假设您正在使用App-Shell模式开发您的网站，并且使用您的 app-shell 缓存首页/。现在当用户访问/something-else时，我们需要从缓存中提供相同的 app-shell。通过cacheMaps可以轻松办到：

new OfflinePlugin({
    cacheMaps: [
        {
            match: function(requestUrl) {
                return new URL('/', location);
            },
            requestTypes: ['navigate']
        }
    ]
})

1
2
3
4
5
6
7
8
9
10

注意，这个功能是通过appShell配置项实现的，所以如果没有更复杂需求的话，您应该更喜欢它。

可用的属性：

match: string | RegExp | function -- 匹配 URL 以映射到缓存。如果是函数，那么它接受2个参数：请求的URL对象以及Request本身。函数的返回值作为新的URL。它必须是一个URL对象。
to: string | function -- 仅当match不是函数时使用。每个 URL 都和urlString.replace(map.match, map.to)相匹配，因此to配置项实际是请求url时调用的String.replace函数的第二个参数。
requestType Array -- 此次映射应当使用的请求类型数组。可以是任何值的组合: navigare、same-origin、cross-origin。示例：requestTypes: ['navigate', 'same-origin']

Caches

caches: 'all' | Object

告诉插件哪些需要缓存及如何缓存。

'all'：意味着在外部配置项中列出的所有项目(所有webpack输出资产)和URL都将在安装时缓存。
Object：对象有三个可能的Array<string | RegExp>字段：main、additional、optional。所有的字段都是可选且默认为空的。

高级用法

传递Object以自定义构建资源的方法。

caches: {
  main: [':rest:'],
  additional: [':externals:'],
  optional: ['*.chunk.js']
}

1
2
3
4
5

在这个例子中，以chunk.js结尾的资源被列入optional缓存中，外部资源则归为additional缓存，其余的则列为main缓存。

特殊关键字:rest来匹配所有未使用/未缓存的静态资源。若要匹配多个资源或动态名称的资源，请使用模式匹配。若添加(不属于webpack构建流程内的)外部资源，请在externals中列出它们，然后再缓存中使用:externals关键字。如果你不想把所有externals都放到同一个部分，那么可以单独列出(示例：additional: ['/external.js'])而非使用:externals关键字。

Cache sections

main: 首先缓存这部分列出的资源(ServiceWorker的install事件)，如果这部分缓存失败————则不会缓存任何资源。因此，这里应包含最重要的资源(如：['index.html', 'main.js'])，没这些网站就歇菜的那种。
additional: 默认情况下仅在 ServiceWorker 中启用。该部分的资源是在main部分成功加载之后才加载的(ServiceWorks的activate事件)。如果有任何资源加载失败，则不会从本部分缓存任何内容，并且所有资源都会被移动到optional部分。如果更改了当前更新策略，则下载失败的资源会被移动到optional部分，所有其他的资源则成功缓存。
optional: 默认情况下仅在 ServiceWorker 中启用。只有从服务器时才缓存的资源。ServiceWorker不会提前下载。

注意：AppCache 不支持有条件或延迟的资源加载，默认情况下忽略additional和optional部分中的资源。要使AppCache缓存所有部分，请设置此选项:

AppCache: {
  caches: ['main', 'additional', 'optional']
}

1
2
3

ServiceWorker: Object | null | false

设置ServiceWorker的缓存。设置null和false可以禁用ServiceWorker。

output: string。配发脚本的相对输出路径(webpack配置中的output.path)。默认：'sw.js'
entry: string。作为ServiceWorker入口/引导文件的相对或绝对路径。对于实现ServiceWorker事件的额外功能和句柄如push、sync等非常有用。默认：空文件.
scope: string。该项十分危险！。在将ServiceWorker部署到生产环境后，不应该更改此选项。更改它可能会损坏缓存，并在用户的设备上留下旧的缓存。当需要在同一域中运行多个项目时，此选项非常有用。默认：''。示例：'my-project'。
events: boolean。为ServiceWorker启用运行时事件。有关受支持的事件，请参阅运行时的install()选项。默认值：false
publicPath: string。提供一种覆盖服务器上ServiceWorker脚本文件位置的方式。应该是生成ServiceWorker的确切路径。默认：null。示例：'/my/new/path/sw.js'
navigationPreload: boolean | Object | ':auto'. 参见ServiceWorker.navigationPreload，默认：auto
prefetchRequest: Object。为预请求提供一种可以指定请求初始配置项的方式(在install事件中的预缓存请求。)。可选值：credentials、headers、mode、cache。默认: { credentials: 'omit', mode: 'cors' }。示例：{ credentials: 'include' }
minify：boolean。如果设置为true或false, ServiceWorker的输出将相应地压缩或不压缩。如果您使用了webpack.optimization.UglifyJsPlugin或terser-webpack-plugin的话，设置为其他值，ServiceWorker输出将被压缩，。默认值：null。

runtime(运行时)

install(options: Object)

开始ServiceWorker/AppCache的安装流。它虽然安全，但每次你的页面加载时都会调用(不要把它包装到任何条件中)。

applyUpdate()

用于为现有安装应用更新。参见下面的install配置项。

update()

检查新ServiceWorker/AppCache的更新。

install()的配置项(options)

import * as OfflinePluginRuntime from 'offline-plugin/runtime';
OfflinePluginRuntime.install({
  onInstalled: () => {}, // 事件在安装 ServiceWorker 或 AppCache 时被调用一次。可用于显示“App已准备好脱机使用”消息。
  onUpdating: () => {}, // AppCache 不支持这一事件。当发现更新并且浏览器开始更新进程时调用。此时，一些资源正在下载。
  onUpdateReady: () => {}, // 当 onupdating 阶段完成时调用。此时所有必需的资源都已下载并准备好进行更新。调用 runtime.applyUpdate() 来应用更新。
  onUpdateFailed: () => {}, // 当 onupdating 阶段因某种原因失败时调用。此时没有下载任何东西，您的代码中的当前更新过程应该被取消或忽略。
  onUpdated: () => {} // 当应用更新时，通过调用 runtime.applyUpdate() 或浏览器本身的其他方式调用。
});

1
2
3
4
5
6
7
8

← prepack-webpack-plugin clean-webpack-plugin →