构建期环境变量

构建期使用的环境变量。

该配置项用于放置仅需要在 NodeJs 环境中使用的环境变量。

对于每一项配置 <KEY>: <value | function(): value>：<KEY> 是属性名（推荐函数使用小写驼峰，常量使用大写下划线式命名），<value> 是环境变量的值。

该环境变量中的代码在 NodeJs 环境下执行，执行结果不会被放入 sw.js 中。

DOMAIN_HOST

类型	说明	默认值
`URL`	网站地址	`new URL('https://www.example.com')`

该项用于告知 swpp 您的网站所在的 URL 地址，swpp 通过该属性判断一个资源是否是外部资源、计算 swpp 文件在线上的地址。

PUBLIC_PATH

类型	说明	默认值
`FilePath`	网站在本地的目录	无

该项用于告知 swpp 您的网站的本地目录，用于计算构建过程时的目录。

注意⚠️：包括 CLI 在内，swpp 所有前端实现必须自动配置该项，用户无需手动填写。

PROJECT_PATH

类型	说明	默认值
`FilePath`	项目根目录	工作目录

该项用于修改项目根目录，除非您知道您在做什么，否则不要修改该项。

注意⚠️：如果框架结构确实需要修改该项，则 swpp 的前端实现必须自动配置该项，用户无需手动填写。

SERVICE_WORKER

类型	说明	默认值
`string`	sw 文件名	`sw`

该项用于告知 swpp 您的 sw 生成的路径及名称，编写时不需要携带拓展名，默认生成到 /sw.js。

JSON_HTML_LIMIT

类型	说明	默认值
`number`	HTML 数量限制，设置为非正整数表示不限制	`0`

该项用于控制单次刷新 HTML 的最大数量，当刷新的数量超过阈值后，swpp 将一次性清除所有的 HTML 缓存。

该项在您修改网站的所有或多数 HTML 时非常有用，可以避免在一个版本的更新内容中写入大量的字符串。

VERSION_LENGTH_LIMIT

类型	说明	默认值
`number`	版本信息长度限制	`1024`

该项用于控制版本文件的最大长度，swpp 保证版本文件中的版本信息的长度之和不超过指定的值。设置为 0 可以禁用长度限制，但会导致版本文件无限制的增长，后面随时可能会禁止设置为 0。

swpp 限制长度的策略是不断移除最远的一个版本号，直到长度满足要求。

SWPP_JSON_FILE

类型	说明	默认值
`object`	JSON 文件的基本信息	省略

该项用于配置与 swpp 与生成和获取数据文件相关的操作，具体的类型和解释如下：

// noinspection TypeScriptUnresolvedReference,JSUnusedLocalSymbols
 
interface Type {
 
    /** 生成的数据文件的目录，默认值：`swpp` */
    swppPath: string
    /** 后台 tracker 信息的文件名，默认值：`tracker.json` */
    trackerPath: string
    /** 版本文件的文件名，默认值：`update.json` */
    versionPath: string
 
    /**
     * 拉取 tracker 文件，默认操作是从网络中拉取文件并解析。
     *
     * 拉取的地址为：`https://{DOMAIN_HOST}/{swppPath}/{trackerPath}`
     */
    fetchTrackerFile: (
      compilation: CompilationData,
    ) => Promise<FileUpdateTracker>
 
    /**
     * 拉取版本文件，默认操作是从网络中拉取文件并解析。
     *
     * 拉取的地址为：`https://{DOMAIN_HOST}/{swppPath}/{versionPath}`
     */
    fetchVersionFile: () => Promise<UpdateJson>
 
}

修改该项配置时，可以仅修改部分字段，比如传入：{ swppPath: 'example/hello' } 可以仅修改 swppPath 的值，而其它的值保持默认。

NETWORK_FILE_FETCHER

类型	说明	默认值
`() => Promise<Response>`	拉取网络文件	`fetch`

该配置项用于修改 swpp 从网络中拉取文件的行为，其类型定义如下：

默认的实现已经可以满足绝大多数要求，大多数情况下不需要修改，仅在遇到以下情况时需要修改：

您使用的 NodeJS 版本不支持 fetch 函数；
你需要为 fetch 配置代理。

ALLOW_NOT_FOUND

类型	说明	默认值
`AllowNotFoundEnum`	404 等级	`ALLOW_STATUS`

该配置项用于设置拉取数据文件时能够接受的 404 级别。共分为三个级别：

ALLOW_ALL: 允许任何形式的 404（response 返回 404 状态码、DNS 解析错误等）
ALLOW_STATUS: 允许 response 返回 404 状态码
REJECT_ALL: 不允许任何形式的 404 错误

当遇到不允许的 404 错误时 swpp 将直接结束构建，设置合理的报错等级可以防止网站被错误地部署到线上，从而导致历史版本丢失。

readLocalFile

类型	说明	默认值
`(path: string) => Promise<crypto.BinaryLike>`	从本地读取一个文件	省略

该配置项用于从本地读取一个文件，其接受一个参数 path，可能为绝对路径也可能为相对路径，默认实现使用 fs 以 UTF-8 编码读取文件。

对于 HTML、CSS、JS 类型的文件，必须返回 string，其它类型的文件只需要满足 crypto.BinaryLike 即可。

isNotFound

类型	说明	默认值
`object`	判断一个请求是否是 404 错误	省略

该配置项用于判断一个请求的结果是否是 404 错误（该配置项仅影响 swpp 生成的数据文件的拉取任务），默认实现如下：

export default {
 
    /**
     * 通过 response 判断是否是 404，在这里返回 true 均会被认定为状态码 404
     *
     * 注意不能直接读取传入的 response 的 body，如果需要修改先 clone 一下
     *
     * @return 返回 `true` 表示判定为 404
     */
 
    response: (response: Response) => response.status == 404,
    /**
     * 当拉取文件报错时通过该函数判断是否是 404
     * @return 返回 `true` 表示判定为 404
     */
    error: (err: any) => err?.cause?.code === 'ENOTFOUND'
 
};

CrossEnv RuntimeCore