🚀 vite-plugin-preloader

智能路由预加载 Vite 插件，一行配置，极致性能！

✨ 特性

• 🎯 一行配置 - 在 vite.config.js 中配置即可，无需修改任何业务代码
• ⚡ 零运行时开销 - 构建时生成，运行时高效执行
• 🎨 自动注入 - 无需手动调用，插件自动将预加载脚本注入 HTML
• 🛠️ 开发友好 - 智能默认配置 + 丰富的调试工具
• 📦 类型安全 - 完整的 TypeScript 支持
• 🔥 热更新支持 - 配置变更时自动更新
• 🎭 状态可视化 - 优雅的加载状态显示，支持多种位置

📦 安装

npm install vite-plugin-preloader
# 或
yarn add vite-plugin-preloader
# 或
pnpm add vite-plugin-preloader
# 或
bun add vite-plugin-preloader

🚀 快速开始

极简配置（推荐）

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import preloader from 'vite-plugin-preloader'

export default defineConfig({
  plugins: [
    vue(),
    preloader({
      routes: [
        '/dashboard',    // 字符串配置，组件路径自动推断
        '/calendar',     // 推断为: @/views/calendar/index.vue
        '/charts',       // 推断为: @/views/charts/index.vue
      ]
    })
  ]
})

就这样！ 插件会自动：

• 🎯 推断组件路径
• 📦 注入预加载脚本
• 🎨 显示加载状态
• 🛠️ 提供调试工具
• ⚙️ 应用智能默认配置

完整配置示例

preloader({
  routes: [
    // 🔥 字符串配置 - 简单直接
    '/dashboard',
    '/user-profile',
    
    // 🎯 对象配置 - 更多控制
    { 
      path: '/calendar', 
      component: '@/views/calendar/CalendarView.vue', // 自定义组件路径
      reason: '日历组件包含 @fullcalendar 全家桶(~500KB)',
      priority: 1  // 高优先级，优先加载
    },
    { 
      path: '/charts', 
      reason: '图表页面包含 echarts、@antv/x6 等重型库',
      priority: 2 
    },
    { 
      path: '/reports', 
      reason: '报表页面包含复杂的数据处理逻辑',
      priority: 3 
    }
  ],
  
  // 🚀 以下所有配置都有智能默认值，可选配置
  delay: 2000,                    // 页面加载后延迟 2 秒开始预加载
  showStatus: true,               // 显示 "🔄 正在优化页面..." 状态
  statusPosition: 'bottom-right', // 状态显示位置
  debug: true                     // 强制开启调试（默认开发环境自动开启）
})

🎯 配置选项

插件选项

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | routes | (string \| PreloadRoute)[] | [] | 必填 预加载路由配置 | | delay | number | 2000 | 延迟时间(ms)，避免影响首屏加载 | | showStatus | boolean | true | 显示加载状态指示器 | | statusPosition | 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right' | 'bottom-right' | 状态指示器位置 | | debug | boolean | 开发环境: true生产环境: false | 调试模式，控制台输出详细日志 |

PreloadRoute 配置

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | path | string | ✅ | 路由路径，如 /dashboard | | component | string | ❌ | 组件路径，不填则自动推断 | | reason | string | ❌ | 预加载原因说明，便于调试和维护 | | priority | number | ❌ | 优先级 1-5（数字越小越先加载），默认 2 |

🛠️ 开发调试

开发环境下，插件自动在浏览器控制台提供调试工具：

// 查看预加载统计信息
window.preloaderDebug.stats()
// 返回: { total: 3, completed: 2, failed: 0, startTime: 1234567890, ... }

// 检查指定路由是否已预加载  
window.preloaderDebug.check('/calendar')
// 返回: true

// 手动重新开始预加载（用于测试）
window.preloaderDebug.restart()

// 显示所有可用的调试命令
window.preloaderDebug.help()

📊 控制台输出示例

插件启动日志

🚀 [预加载插件] 已启用，配置了 3 个路由
📋 [预加载插件] 路由列表: ["/dashboard", "/calendar", "/charts"]
⚙️ [预加载插件] 配置选项: { delay: 2000, showStatus: true, statusPosition: "bottom-right", debug: true }
🎨 [预加载插件] 注入预加载脚本到 HTML

预加载执行日志

🚀 [预加载] 开始预加载 3 个页面
✅ [预加载] /dashboard (156ms) - 自动推断的预加载页面
✅ [预加载] /calendar (234ms) - 日历组件包含 @fullcalendar 全家桶(~500KB)
✅ [预加载] /charts (456ms) - 图表页面包含 echarts、@antv/x6 等重型库
🎉 [预加载] 完成! 耗时 1234ms
🛠️ 预加载调试工具: window.preloaderDebug

🎨 状态显示效果

插件会在页面显示优雅的加载状态：

🔄 正在优化页面... 2/3

• 位置可配置：四个角落任选
• 自动隐藏：预加载完成后淡出消失
• 不干扰用户：pointer-events: none，不阻挡交互

🔧 最佳实践

1. 路由配置策略

routes: [
  // 🔥 核心页面 - 用户必访，优先级最高
  { path: '/dashboard', priority: 1, reason: '用户首页，访问频率最高' },
  
  // ⚡ 常用页面 - 功能页面，中等优先级
  { path: '/calendar', priority: 2, reason: '日历功能，包含大型日期库' },
  { path: '/contacts', priority: 2, reason: '联系人管理，数据量大' },
  
  // 📊 专业工具 - 低频但重型，最后加载
  { path: '/reports', priority: 3, reason: '报表页面，包含复杂图表库' },
  { path: '/admin', priority: 3, reason: '管理后台，权限要求高' }
]

2. 智能路径推断

插件自动将路由路径转换为组件路径：

// 路径推断规则
'/dashboard'           → '@/views/dashboard/index.vue'
'/user-profile'        → '@/views/user-profile/index.vue'
'/admin/users'         → '@/views/admin/users/index.vue'
'/demo/13-calendar'    → '@/views/demo/13-calendar/index.vue'

3. 性能优化建议

{
  // ✅ 推荐：给出明确的预加载原因
  path: '/calendar',
  reason: '日历组件包含 @fullcalendar(~400KB) + moment.js(~60KB)',
  priority: 2
},

{
  // ✅ 推荐：重型页面单独配置优先级
  path: '/data-visualization', 
  reason: '数据可视化包含 d3.js + echarts + three.js (~1.2MB)',
  priority: 3  // 低优先级，避免影响关键页面
}

4. 开发环境优化

// vite.config.js
preloader({
  routes: [/* ... */],
  
  // 开发环境配置
  ...(process.env.NODE_ENV === 'development' ? {
    debug: true,        // 开发环境显示详细日志
    delay: 1000,        // 开发环境快速启动
    showStatus: true    // 显示状态便于调试
  } : {
    debug: false,       // 生产环境静默运行
    delay: 3000,        // 生产环境延迟更久，确保首屏稳定
    showStatus: false   // 生产环境不显示状态
  })
})

🚀 工作原理

构建时

1. 配置解析 - 解析用户配置，应用智能默认值
2. 路径推断 - 自动推断未指定的组件路径
3. 代码生成 - 生成优化的预加载脚本
4. HTML注入 - 将脚本直接注入到 HTML <head> 中

运行时

1. DOM就绪检测 - 等待页面 DOM 加载完成
2. 延迟启动 - 根据配置延迟指定时间后启动
3. 优先级排序 - 按 priority 值从小到大排序
4. 串行加载 - 顺序预加载，避免并发阻塞
5. 状态反馈 - 实时更新加载状态和统计信息

🎯 适用场景

• ✅ Vue SPA 应用 - 单页应用路由预加载
• ✅ 后台管理系统 - 管理页面通常较重，预加载效果明显
• ✅ 数据可视化应用 - 图表库体积大，预加载能显著提升体验
• ✅ 工具型应用 - 功能页面复杂，用户操作流程相对固定

❓ 常见问题

Q: 预加载会影响首屏性能吗？

A: 不会。插件默认延迟 2 秒启动，确保首屏渲染完成后才开始预加载。

Q: 如何判断哪些页面需要预加载？

A: 建议预加载：1) 用户高频访问的页面 2) 包含大型第三方库的页面 3) 数据处理复杂的页面。

Q: 开发环境下看不到预加载效果？

A: 开发环境下模块已经在内存中，预加载效果不明显。可以通过控制台日志确认插件正常工作。

Q: 可以配置生产环境不预加载吗？

A: 可以。在配置中添加环境判断即可：

preloader({
  routes: process.env.NODE_ENV === 'production' ? [] : ['/dashboard', '/calendar']
})

🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建你的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交你的修改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启一个 Pull Request

📄 许可证

MIT © ChenYu

🎯 一行配置，极致性能！让你的 Vue 应用飞起来！ 🚀