构建期环境变量

构建期使用的环境变量。

该配置项用于放置仅需要在 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

类型	说明	默认值
`string`	网站在本地的目录，必须以 `/` 或 `\` 结尾	无

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

注意⚠️：包括 CLI 在内，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

类型	说明	默认值
`NetworkFileHandler`	拉取网络文件	`FiniteConcurrencyFetcher`

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

import * as http from 'node:http'
 
// noinspection JSUnusedLocalSymbols
interface NetworkFileHandler {
 
    /** 最大并发量，当并发量超过此限制时，后到达的请求应当等待队列中的请求完成。默认为：100 */
    limit: number
    /** 单个连接的超时时间（毫秒），默认为：5000 */
    timeout: number
    /** 拉取文件时使用的 referer，默认为：https://swpp.example.com */
    referer: string
    /** 拉取文件时使用的 ua，默认为：swpp-backends */
    userAgent: string
    /** HTTP 代理 */
    proxy: http.Agent
    /** 需要额外写入的 header */
    headers: { [name: string]: string }
 
    /** 拉取文件 */
    fetch(request: RequestInfo | URL): Promise<Response>
 
    /** 获取指定文件的类型 */
    getUrlContentType(url: string, response?: Response): string
 
    /**
     * 判断请求失败后是否重试
     * @param request 请求内容
     * @param count 已重试次数（不包括本次）
     * @param err 失败的原因
     */
    isRetry(request: RequestInfo | URL, count: number, err: any): boolean
 
    /**
     * 获取备用 URL 列表
     * @param url
     * @return 返回的数组中的第一个元素将用于替换原有的 URL
     */
    getStandbyList(url: string | URL): (string | URL)[]
 
}

默认的实现已经可以满足绝大多数要求，大多数情况下不需要修改 fetch 和 getUrlContentType。对于内置的 FiniteConcurrencyFetcher 实现，还在 NetworkFileHandler 基础上额外添加了 retryLimit: number 字段，默认为 3，用于控制请求超时后的最大重试次数。

如果需要使用本地代理，可以提供 proxy 字段，下面以 https-proxy-agent 为例：

import { defineCompilationEnv } from 'swpp-backends'
import { HttpsProxyAgent } from 'https-proxy-agent'
 
defineCompilationEnv({
    NETWORK_FILE_FETCHER: {
        proxy: new HttpsProxyAgent('http://127.0.0.1:10809')
    }
})

ALLOW_NOT_FOUND

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

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

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

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

isStable

类型	说明	默认值
`(url: URL) => boolean`	检查一个链接是否是稳定的	`() => false`

该配置项用于检查一个链接是否是稳定的，也就是 URL 不变时，使用这个 URL 拉取到的结果永远不变。

合理地设置该项可以加快 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