Resource Fallback

简体中文

English

简体中文

English

外观

@resource-fallback/core / types

types ​

Interfaces ​

CircuitOptions ​

Defined in: types.ts:20

Properties ​

cooldown? ​
ts
optional cooldown?: number;

Defined in: types.ts:24

熔断后的冷却时长（ms），到期后重新尝试该 host。默认 30000。

shareAcrossTabs? ​
ts
optional shareAcrossTabs?: boolean;

Defined in: types.ts:31

将熔断状态持久化到 localStorage，让同源下多个标签页共享已挂掉的 host 信息。 其他 tab 通过 storage 事件实时感知变更。 设为 false 则仅在当前页面内存中保持熔断状态，tab 间互不影响。 默认 true。存储不可用时优雅降级。

storageTtl? ​
ts
optional storageTtl?: number;

Defined in: types.ts:36

localStorage 中熔断条目的存活时长（ms）。超过此时间的条目在读取时自动丢弃， 避免过期数据残留导致用户长时间无法正常加载。默认 120000（2 分钟）。

threshold? ​
ts
optional threshold?: number;

Defined in: types.ts:22

同一 host 连续失败多少次后触发熔断。默认 5。

FallbackRule ​

Defined in: types.ts:39

Properties ​

circuit? ​
ts
optional circuit?: CircuitOptions;

Defined in: types.ts:50

match ​
ts
match: MatchPattern;

Defined in: types.ts:41

决定该规则是否应用于某个失败 URL。

retry? ​
ts
optional retry?: RetryOptions;

Defined in: types.ts:49

urls ​
ts
urls: string[];

Defined in: types.ts:48

有序的候选 base URL 列表。当某 URL 的重试预算耗尽后，运行时会用下一个候选 替换匹配的前缀。最后一个通常指向自建源站。

每项应为 base URL 前缀，例如 https://cdn.example.com/。

HtmlTag ​

Defined in: types.ts:108

Properties ​

attributes ​
ts
attributes: HtmlTagAttributes;

Defined in: types.ts:111

innerHTML? ​
ts
optional innerHTML?: string;

Defined in: types.ts:112

tagName ​
ts
tagName: "script" | "link";

Defined in: types.ts:109

voidTag? ​
ts
optional voidTag?: boolean;

Defined in: types.ts:110

HtmlTagAttributes ​

Defined in: types.ts:104

Indexable ​

ts
[name: string]: string | boolean | undefined

NormalizedServiceWorkerOptions ​

Defined in: types.ts:144

Properties ​

cache ​
ts
cache: object;

Defined in: types.ts:150

cacheOpaque ​
ts
cacheOpaque: boolean;
enabled ​
ts
enabled: boolean;
enabled ​
ts
enabled: boolean;

Defined in: types.ts:145

fallbackOnOpaque ​
ts
fallbackOnOpaque: boolean;

Defined in: types.ts:149

includeStyleImports ​
ts
includeStyleImports: boolean;

Defined in: types.ts:148

path ​
ts
path: string;

Defined in: types.ts:146

scope ​
ts
scope: string;

Defined in: types.ts:147

PluginOptions ​

Defined in: types.ts:175

插件构建时的配置选项。不在 RuntimeConfig 中的字段仅供 webpack/vite 插件消费，序列化到浏览器前会被剥离。

Extends ​

Properties ​

debug? ​
ts
optional debug?: DebugFlag;

Defined in: types.ts:99

  • true 始终打印日志
  • false 永不打印（生产环境默认）
  • 'auto' 当 localStorage.__RF_DEBUG__ 为真值时打印
Inherited from ​

RuntimeConfig.debug

defaults? ​
ts
optional defaults?: object;

Defined in: types.ts:82

circuit? ​
ts
optional circuit?: CircuitOptions;
retry? ​
ts
optional retry?: RetryOptions;
Inherited from ​

RuntimeConfig.defaults

disableCookie? ​
ts
optional disableCookie?: string;

Defined in: types.ts:93

值为 1 时禁用运行时的 cookie 名。默认 __rf_disable。

Inherited from ​

RuntimeConfig.disableCookie

disableGlobals? ​
ts
optional disableGlobals?: string[];

Defined in: types.ts:89

除 __RF_DISABLE__ 外额外检查的全局 kill-switch 变量名。

Inherited from ​

RuntimeConfig.disableGlobals

disableQueryParam? ​
ts
optional disableQueryParam?: string;

Defined in: types.ts:91

设为 off 时禁用运行时的 URL 查询参数名。默认 __rf。

Inherited from ​

RuntimeConfig.disableQueryParam

enableDev? ​
ts
optional enableDev?: boolean;

Defined in: types.ts:177

在 dev/serve 模式下也注入运行时。默认 false。

externalRuntime? ​
ts
optional externalRuntime?: boolean;

Defined in: types.ts:184

将运行时作为独立资源输出并通过 <script src> 引用，而非内联。 当 CSP 禁止 unsafe-inline 时适用。默认 false。

externalRuntimePath? ​
ts
optional externalRuntimePath?: string;

Defined in: types.ts:186

当 externalRuntime 为 true 时使用的外链路径。默认 /__rf/runtime.js。

hooks? ​
ts
optional hooks?: RuntimeHooks;

Defined in: types.ts:83

Inherited from ​

RuntimeConfig.hooks

htmlInject? ​
ts
optional htmlInject?: "head-prepend" | "head-append";

Defined in: types.ts:190

注入到 <head> 中的位置。默认 head-prepend（最前面）。

injectPreconnect? ​
ts
optional injectPreconnect?: boolean;

Defined in: types.ts:188

为每个 fallback host 注入 <link rel=preconnect>。默认 true。

nonce? ​
ts
optional nonce?: string;

Defined in: types.ts:179

附加到注入的 <script> 标签上的 CSP nonce。

rules ​
ts
rules: FallbackRule[];

Defined in: types.ts:81

Inherited from ​

RuntimeConfig.rules

serviceWorker? ​
ts
optional serviceWorker?: boolean | ServiceWorkerOptions;

Defined in: types.ts:85

Service Worker hybrid 资源回退配置。默认关闭。

Inherited from ​

RuntimeConfig.serviceWorker

serviceWorkerManifest? ​
ts
optional serviceWorkerManifest?: ResourceFallbackManifest;

Defined in: types.ts:87

构建期生成的资源 manifest，仅在 Service Worker 模式下使用。

Inherited from ​

RuntimeConfig.serviceWorkerManifest

sri? ​
ts
optional sri?: SriPolicy;

Defined in: types.ts:101

SRI 处理策略。默认 'strip'。

Inherited from ​

RuntimeConfig.sri

ResourceFallbackManifest ​

Defined in: types.ts:165

Properties ​

assets ​
ts
assets: ResourceFallbackManifestAsset[];

Defined in: types.ts:168

rules ​
ts
rules: FallbackRule[];

Defined in: types.ts:167

version ​
ts
version: string;

Defined in: types.ts:166

ResourceFallbackManifestAsset ​

Defined in: types.ts:159

Properties ​

owner ​
ts
owner: ResourceFallbackAssetOwner;

Defined in: types.ts:162

type ​
ts
type: ResourceFallbackAssetType;

Defined in: types.ts:161

url ​
ts
url: string;

Defined in: types.ts:160

RetryOptions ​

Defined in: types.ts:9

Properties ​

baseDelay? ​
ts
optional baseDelay?: number;

Defined in: types.ts:13

首次重试前的初始延迟（ms）。默认 300。

jitter? ​
ts
optional jitter?: boolean;

Defined in: types.ts:17

为每次延迟添加最多 25% 的随机抖动，分散重试风暴。默认 true。

max? ​
ts
optional max?: number;

Defined in: types.ts:11

同一 URL 的重试预算。超过此次数后切换到下一个 URL。默认 2。

maxDelay? ​
ts
optional maxDelay?: number;

Defined in: types.ts:15

指数退避的延迟上限（ms）。默认 3000。

RuntimeConfig ​

Defined in: types.ts:80

浏览器运行时使用的配置对象。

注意：该对象会被 JSON 序列化并嵌入页面，所有值必须是原始类型（不能有函数）。 FallbackRule.match 此处仅支持 string 或 RegExp。 （在运行时通过 JS 调用 install() 时才支持函数形式的 match。）

Extended by ​

Properties ​

debug? ​
ts
optional debug?: DebugFlag;

Defined in: types.ts:99

  • true 始终打印日志
  • false 永不打印（生产环境默认）
  • 'auto' 当 localStorage.__RF_DEBUG__ 为真值时打印
defaults? ​
ts
optional defaults?: object;

Defined in: types.ts:82

circuit? ​
ts
optional circuit?: CircuitOptions;
retry? ​
ts
optional retry?: RetryOptions;
disableCookie? ​
ts
optional disableCookie?: string;

Defined in: types.ts:93

值为 1 时禁用运行时的 cookie 名。默认 __rf_disable。

disableGlobals? ​
ts
optional disableGlobals?: string[];

Defined in: types.ts:89

除 __RF_DISABLE__ 外额外检查的全局 kill-switch 变量名。

disableQueryParam? ​
ts
optional disableQueryParam?: string;

Defined in: types.ts:91

设为 off 时禁用运行时的 URL 查询参数名。默认 __rf。

hooks? ​
ts
optional hooks?: RuntimeHooks;

Defined in: types.ts:83

rules ​
ts
rules: FallbackRule[];

Defined in: types.ts:81

serviceWorker? ​
ts
optional serviceWorker?: boolean | ServiceWorkerOptions;

Defined in: types.ts:85

Service Worker hybrid 资源回退配置。默认关闭。

serviceWorkerManifest? ​
ts
optional serviceWorkerManifest?: ResourceFallbackManifest;

Defined in: types.ts:87

构建期生成的资源 manifest，仅在 Service Worker 模式下使用。

sri? ​
ts
optional sri?: SriPolicy;

Defined in: types.ts:101

SRI 处理策略。默认 'strip'。

RuntimeHooks ​

Defined in: types.ts:58

Properties ​

onError? ​
ts
optional onError?: (e) => void;

Defined in: types.ts:66

所有候选 URL（包括源站）均失败后触发。 不会自动执行 location.reload() ——由业务决定如何兜底。

Parameters ​
e ​

ErrorEvent

Returns ​

void

onFallback? ​
ts
optional onFallback?: (e) => void;

Defined in: types.ts:60

Parameters ​
e ​

FallbackEvent

Returns ​

void

onRetry? ​
ts
optional onRetry?: (e) => void;

Defined in: types.ts:59

Parameters ​
e ​

RetryEvent

Returns ​

void

onSuccess? ​
ts
optional onSuccess?: (e) => void;

Defined in: types.ts:61

Parameters ​
e ​

SuccessEvent

Returns ​

void

ServiceWorkerOptions ​

Defined in: types.ts:115

Properties ​

cache? ​
ts
optional cache?: object;

Defined in: types.ts:138

Cache API 策略。默认仅缓存 fallback 成功的非 opaque 2xx 响应。

cacheOpaque? ​
ts
optional cacheOpaque?: boolean;
enabled? ​
ts
optional enabled?: boolean;
enabled? ​
ts
optional enabled?: boolean;

Defined in: types.ts:117

是否启用 Hybrid Service Worker。默认 false。

fallbackOnOpaque? ​
ts
optional fallbackOnOpaque?: boolean;

Defined in: types.ts:136

启用 CORS 探测以检测跨源 HTTP 错误（如 502/503）。默认 false。

开启后，SW 对 no-cors 请求先尝试 cors 模式（credentials: omit）， 如果 CDN 返回了 Access-Control-Allow-Origin 头，就能拿到真实状态码， 非 2xx 响应会触发 retry/fallback。

如果 CDN 不支持 CORS，会自动降级回 no-cors（opaque 响应被接受）； 此时仅网络级故障（DNS/连接失败）能触发 fallback，HTTP 错误无法检测。

建议在 CDN 配置了 Access-Control-Allow-Origin 头时开启。

includeStyleImports? ​
ts
optional includeStyleImports?: boolean;

Defined in: types.ts:123

是否允许通过 CSS referrer 接管受控 @import。默认 true。

path? ​
ts
optional path?: string;

Defined in: types.ts:119

Service Worker 文件 URL。默认跟随 scope：/ → /rf-sw.js，/app/ → /app/rf-sw.js。

scope? ​
ts
optional scope?: string;

Defined in: types.ts:121

Service Worker scope。默认 /。

Type Aliases ​

DebugFlag ​

ts
type DebugFlag = boolean | "auto";

Defined in: types.ts:71

ErrorEvent ​

ts
type ErrorEvent = object;

Defined in: types.ts:56

Properties ​

reason? ​
ts
optional reason?: unknown;

Defined in: types.ts:56

url ​
ts
url: string;

Defined in: types.ts:56

FallbackEvent ​

ts
type FallbackEvent = object;

Defined in: types.ts:54

Properties ​

from ​
ts
from: string;

Defined in: types.ts:54

reason? ​
ts
optional reason?: unknown;

Defined in: types.ts:54

to ​
ts
to: string;

Defined in: types.ts:54

MatchPattern ​

ts
type MatchPattern = string | RegExp | ((url) => boolean);

Defined in: types.ts:7

用于判断失败 URL 是否受某条规则管辖的匹配模式。

  • string 前缀匹配（区分大小写）
  • RegExp 对 URL 做正则测试
  • 函数针对每个 URL 自行决定

ResolveResult ​

ts
type ResolveResult = 
  | {
  attempt: number;
  delay: number;
  kind: "retry";
  url: string;
}
  | {
  attempt: number;
  delay: number;
  from: string;
  kind: "fallback";
  url: string;
}
  | {
  kind: "giveup";
  reason: "rules-exhausted" | "no-match";
};

Defined in: types.ts:193

ResourceFallbackAssetOwner ​

ts
type ResourceFallbackAssetOwner = "page" | "sw";

Defined in: types.ts:157

ResourceFallbackAssetType ​

ts
type ResourceFallbackAssetType = "script" | "style" | "image" | "font" | "media" | "asset";

Defined in: types.ts:156

RetryEvent ​

ts
type RetryEvent = object;

Defined in: types.ts:53

Properties ​

attempt ​
ts
attempt: number;

Defined in: types.ts:53

url ​
ts
url: string;

Defined in: types.ts:53

SriPolicy ​

ts
type SriPolicy = "strip" | "keep" | "strict";

Defined in: types.ts:69

SuccessEvent ​

ts
type SuccessEvent = object;

Defined in: types.ts:55

Properties ​

attempts ​
ts
attempts: number;

Defined in: types.ts:55

url ​
ts
url: string;

Defined in: types.ts:55