Resource Fallback

简体中文

English

简体中文

English

外观

简介 ​

什么是 resource-fallback ​

resource-fallback 是一个零心智负担的前端资源回退方案。它为 Webpack 与 Vite 构建产物（同步 / 异步 JS、CSS）提供运行时 重试 → 多 CDN 回退 → 回源 能力，业务代码无需任何改动。

项目包含三个 npm 包：

包说明
@resource-fallback/core浏览器 IIFE 运行时 + Node 端工具函数
@resource-fallback/vite-pluginVite 4+ 插件
@resource-fallback/webpack-pluginWebpack 5+ 插件

为什么需要资源回退 ​

前端静态资源通常托管在 CDN 上。当主 CDN 出现 DNS 故障、网络抖动或区域性不可用时，页面可能出现白屏、样式丢失或懒加载模块失败。

传统做法需要在业务代码中手动处理加载失败，或在网关层做复杂路由。resource-fallback 在构建时注入运行时、运行时自动拦截失败，按配置依次重试同一 URL、切换到备用 CDN、最终回源，整个过程对业务透明。

适用场景

  • 多 CDN 容灾与主备切换
  • 静态资源加载失败时的自动降级
  • 需要监控上报的资源 fallback 链路

核心架构总览 ​

回退流程 ​

包结构 ​

包说明版本信息
@resource-fallback/core浏览器 IIFE 运行时 + Node 端工具函数见 npm 页面 / package.json
@resource-fallback/vite-pluginVite 4+ 插件见 npm 页面 / package.json
@resource-fallback/webpack-pluginWebpack 5+ 插件见 npm 页面 / package.json

@resource-fallback/core ​

核心运行时与构建工具：

  • RecoveryCoordinator — 页面侧恢复决策引擎，统一负责规则选择、retry / fallback、deadline、取消与事件
  • Retry — 指数退避 + 抖动
  • Circuit Registry — per-host 熔断状态；页面侧当前只有一个 registry，支持 localStorage 跨 Tab 共享
  • Observer — 监听 <script> / <link> 的 error 事件
  • Adapter — Vite / Webpack / SystemJS / SW 适配器，负责 transport 与 ownership 接入
  • buildInjectedTags() — 生成注入 HTML 的标签
  • getRuntimeCode() — 获取 IIFE 运行时源码

@resource-fallback/vite-plugin ​

Vite 构建集成，详见 Vite 集成：

  • transformIndexHtml HTML 注入
  • 动态 import() 包装
  • 可选 Hybrid SW 资产生成

当前页面 runtime 还有三个需要明确的限制：

  • window.__RF__.url(filename) 只会使用第一条已编译规则的 base 构造首轮 URL，不会跳过已熔断 host；
  • 规则会先按 base 长度降序编译；恢复开始后，RecoveryCoordinator 会根据初始 URL 选中一条规则，并沿该规则的有序候选继续恢复；
  • 页面侧目前只初始化一个 circuit registry，而不是每条规则各自一个。

@resource-fallback/webpack-plugin ​

Webpack 构建集成，详见 Webpack 集成：

  • RuntimeModule 注入，patch __webpack_require__.l
  • html-webpack-plugin 集成 HTML 注入
  • 可选 Hybrid SW 资产生成

下一步 ​