vite-plugin-preloader

在用户点击之前，页面已经就绪 —— Vite 路由智能预加载插件

安装 · 快速开始 · 配置选项 · 工作原理 · FAQ

它解决什么问题

路由懒加载把首屏做小了，代价是用户第一次点击某个页面时要现场下载 chunk——重型页面（报表、富文本、地图）会白屏等待。

本插件在页面空闲时提前拉取你指定的路由 chunk：

• 开发环境：注入 <link rel="modulepreload">，dev server 直接管 chunk，秒级生效
• 生产构建：在 generateBundle 阶段扫描产物匹配真实 chunk 路径（含 hash、含 base），由一段无依赖的内联脚本在页面 load 完成 delay 毫秒后注入 <link rel="prefetch">——浏览器空闲时下载、点击即用
• JS 与 CSS 成组预取：路由组件引入的样式产物（cssCodeSplit 拆分）随 chunk 一起预取，切换页面不再现拉样式
• 省流/2G 网络自动跳过预取，SSR 构建自动跳过，可选状态角标观察预加载进度
• 框架无关：Vue / React / Svelte 均可，匹配约定基于目录与扩展名，不依赖路由库

安装

pnpm add vite-plugin-preloader -D
# 或
npm install vite-plugin-preloader --save-dev

快速开始

// vite.config.ts
import { defineConfig } from 'vite'
import preloader from 'vite-plugin-preloader'

export default defineConfig({
  plugins: [
    preloader({
      routes: ['/dashboard', '/report/detail', '/editor'],
    }),
  ],
})

路由组件多数情况不用写 component——默认按 @/views/{path}/index.vue 推断，未命中时自动降级尝试目录（views/pages）× 扩展名（vue/js/ts/jsx/tsx）× 文件形态（{path}/index.*、{path}.*）的约定组合，最后按 /{views|pages}/{path}(/index)? 结构在产物里兜底匹配；实在特殊的路由再用对象格式显式指定：

preloader({
  routes: [
    '/dashboard',                                    // 智能匹配，无需写 component
    { path: '/report/detail', component: 'src/views/report/DetailPage.vue', reason: '高频入口' },
  ],
  exclude: ['/404', '/login'],
})

含 :param 的动态路由会被自动过滤，避免预取无意义的参数页。已被入口 chunk 静态依赖（浏览器本就会立即加载）的组件会自动跳过，不做无谓 prefetch。

配置选项

PreloadRoute 对象格式：

两种生产预取策略（strategy）：

• 'all'（默认）：页面 load 完成 delay 毫秒后，按 priority 分批 prefetch 全部配置路由——简单可预期，适合管理后台等路由数可控的场景
• 'viewport'：只预取视口内或即将点击的 <a href> 对应路由（IntersectionObserver + pointerover 事件委托），SPA 动态渲染的链接天然覆盖——流量友好，适合内容站/移动端 H5

智能匹配

不写 component 时按以下顺序在构建产物中定位路由 chunk（dev 同样适用）：

1. 默认推断 @/views/{path}/index.vue
2. 约定候选：views/pages 目录 × {path}/index.* 与 {path}.* × vue/js/ts/jsx/tsx 扩展名
3. 结构兜底：产物模块路径以 /{views|pages}/{path}(/index)? 结尾即命中

显式写的 component 永远优先；写错了也会被上述候选自动救回。

调度与观测

• priority 分批：生产按 priority 升序分批预取（每批 4 个路由，全部落定或 8s 超时后放行下一批），弱网不挤占连接；同 priority 时小 chunk 优先，更快的进入缓存
• 命中率观测（debug 开启时）：控制台可用 window.__preloaderDebug.stats() 查看 { prefetched, hits, misses }——预取完成数、点击时命中/未命中计数，用它验证路由清单选得准不准
• 防御：路由超过 12 个时 debug 日志会警告（浏览器 prefetch 缓存有限且按 LRU 逐出，建议精简或改 viewport 模式）

与 Vite / 平台能力的分工

工作原理

1. configResolved：读取 alias / root / base / command，解析路由到组件文件；动态路由（:param）与 exclude 命中的路由被过滤
2. 开发模式：transformIndexHtml 注入 <link rel="modulepreload">（dev server 直接解析源文件，预热转换缓存）
3. 生产构建：generateBundle 扫描产物，按「显式路径 → 约定候选 → 结构兜底」智能匹配真实 chunk 文件（含 hash、含 base 的最终 URL，路径经 realpath 归一，symlink/monorepo 场景不失配），并把路由数据写入一段内联脚本注入 HTML——脚本在页面 load 完成 delay 毫秒后按 strategy 创建 <link rel="prefetch">（all 分批 / viewport 视口触发），不依赖猜路径，manualChunks 拆分也能正确匹配
4. 省流保护：检测到 saveData 或 2G/慢速网络时自动跳过预取，不消耗用户流量
5. 状态提示：可选显示预加载进度角标（用 performance 记录初始化已完成数，不会误卡进度），全部完成后自动消失
6. SSR：apply 钩子识别 SSR 构建，不注入客户端脚本

FAQ

兼容性

版本历史

见 CHANGELOG.md、GitHub Releases 与 提交记录。

贡献

欢迎提交 Issue 与 Pull Request。

许可证

MIT © 2025-present CHENY

作者

CHENY · GitHub @ChenyCHENYU