vite-plugin-preloader 1.1.3 → 2.0.1

package/README.md

@@ -1,293 +1,195 @@
 # 🚀 vite-plugin-preloader
 
-智能路由预加载 Vite 插件，一行配置，极致性能！
+> 治好你的"页面加载焦虑症"——精确控制指定路由的预加载时机，在用户点击之前静默预取重型页面，让组件切换瞬间响应。
 
-## ✨ 特性
+[![npm version](https://img.shields.io/npm/v/vite-plugin-preloader)](https://www.npmjs.com/package/vite-plugin-preloader)
+[![Vite](https://img.shields.io/badge/Vite-5~8-646cff)](https://vitejs.dev)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-- 🎯 **一行配置** - 在 `vite.config.js` 中配置即可，无需修改任何业务代码
-- ⚡ **零运行时开销** - 构建时生成，运行时高效执行
-- 🎨 **自动注入** - 无需手动调用，插件自动将预加载脚本注入 HTML
-- 🛠️ **开发友好** - 智能默认配置 + 丰富的调试工具
-- 📦 **类型安全** - 完整的 TypeScript 支持
-- 🔥 **热更新支持** - 配置变更时自动更新
-- 🎭 **状态可视化** - 优雅的加载状态显示，支持多种位置
+你是否经历过这样的痛苦：
+- 📊 点击图表页面，转圈 3 秒才显示
+- 📅 打开日历组件，echarts 慢慢加载
+- 💸 用户等不及直接关闭页面
+
+**别再让用户等待了！** 这个插件在构建阶段将路由组件映射到真实 chunk，向 HTML 注入 `<link rel="prefetch">` 标签，浏览器空闲时自动拉取目标资源；配合状态 UI 和调试工具，帮你精确控制哪些页面需要提前预取、哪些不需要。
+
+## ⚡ 效果对比
+
+```
+❌ 没有预加载：点击 → 等待 3s → 页面显示
+✅ 使用预加载：点击 → 瞬间显示（已预取到缓存）🎉
+```
+
+## 🎯 核心特性
+
+- **🌐 浏览器原生** - 使用 `<link rel="prefetch">`，由浏览器空闲时调度，零 JS 运行时开销
+- **📦 bundle 感知** - 构建时扫描 Rollup/Rolldown bundle，注入真实 chunk hash 路径，生产环境 100% 有效
+- **🛡️ 防御完善** - routes 防 undefined 崩溃、动态路由参数（`:id`）自动过滤、exclude 排除支持
+- **🔌 网络感知** - 检测省流模式 / 2G 网络，自动跳过状态 UI，不做无谓消耗
+- **🚫 SSR 安全** - SSR 构建时自动跳过，不污染服务端
+- **🎨 状态提示** - 可选的右下角进度 UI，监听 prefetch link 加载事件驱动
+- **🛠️ 调试工具** - `window.__preloaderDebug` 方便在浏览器控制台检查预加载状态
+- **🔷 完整类型** - TypeScript 类型定义与实现完全一致，支持 Vite 5 / 6 / 7 / 8
 
 ## 📦 安装
 
 ```bash
-npm install vite-plugin-preloader
-# 或
-yarn add vite-plugin-preloader
-# 或
-pnpm add vite-plugin-preloader
-# 或
-bun add vite-plugin-preloader
+npm i vite-plugin-preloader -D
+# or
+bun add vite-plugin-preloader -D
 ```
 
-## 🚀 快速开始
+## 🚀 快速配置
 
-### 极简配置（推荐）
+### 懒人模式（推荐）
 
 ```js
-// vite.config.js
-import { defineConfig } from 'vite'
-import vue from '@vitejs/plugin-vue'
+// vite.config.js / vite.config.ts
 import preloader from 'vite-plugin-preloader'
 
 export default defineConfig({
   plugins: [
     vue(),
     preloader({
-      routes: [
-        '/dashboard',    // 字符串配置，组件路径自动推断
-        '/calendar',     // 推断为: @/views/calendar/index.vue
-        '/charts',       // 推断为: @/views/charts/index.vue
-      ]
+      routes: ['/dashboard', '/charts', '/calendar']
     })
   ]
 })
 ```
 
-**就这样！** 插件会自动：
-- 🎯 推断组件路径
-- 📦 注入预加载脚本
-- 🎨 显示加载状态
-- 🛠️ 提供调试工具
-- ⚙️ 应用智能默认配置
-
-### 完整配置示例
+### 精细化配置
 
 ```js
 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 
-    }
+    { path: '/dashboard',  reason: '主页面，必须快',         priority: 1 },
+    { path: '/charts',     reason: 'echarts 太重了',         priority: 2 },
+    { path: '/calendar',   reason: 'fullcalendar 500KB',     priority: 3 },
+    // 组件路径不在默认约定（@/views/{path}/index.vue）时手动指定
+    { path: '/editor',     component: '@/pages/editor/Editor.vue', priority: 1 }
   ],
-  
-  // 🚀 以下所有配置都有智能默认值，可选配置
-  delay: 2000,                    // 页面加载后延迟 2 秒开始预加载
-  showStatus: true,               // 显示 "🔄 正在优化页面..." 状态
-  statusPosition: 'bottom-right', // 状态显示位置
-  debug: true                     // 强制开启调试（默认开发环境自动开启）
+  delay: 1500,            // 状态 UI 延迟出现（ms），不影响 prefetch 时机
+  debug: true,            // 开发时开启，控制台打印预加载信息
+  showStatus: true,       // 右下角进度提示
+  statusPosition: 'bottom-right',
+  exclude: ['/login', '/404', '/403']  // 不需要预加载的路由
 })
 ```
 
-## 🎯 配置选项
-
-### 插件选项
-
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `routes` | `(string \| PreloadRoute)[]` | `[]` | **必填** 预加载路由配置 |
-| `delay` | `number` | `2000` | 延迟时间(ms)，避免影响首屏加载 |
-| `showStatus` | `boolean` | `true` | 显示加载状态指示器 |
-| `statusPosition` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `'bottom-right'` | 状态指示器位置 |
-| `debug` | `boolean` | `开发环境: true`<br>`生产环境: false` | 调试模式，控制台输出详细日志 |
+**就这样！** 构建后打开页面源码，你会看到：
 
-### PreloadRoute 配置
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `path` | `string` | ✅ | 路由路径，如 `/dashboard` |
-| `component` | `string` | ❌ | 组件路径，不填则自动推断 |
-| `reason` | `string` | ❌ | 预加载原因说明，便于调试和维护 |
-| `priority` | `number` | ❌ | 优先级 1-5（数字越小越先加载），默认 2 |
-
-## 🛠️ 开发调试
-
-开发环境下，插件自动在浏览器控制台提供调试工具：
-
-```js
-// 查看预加载统计信息
-window.preloaderDebug.stats()
-// 返回: { total: 3, completed: 2, failed: 0, startTime: 1234567890, ... }
-
-// 检查指定路由是否已预加载  
-window.preloaderDebug.check('/calendar')
-// 返回: true
-
-// 手动重新开始预加载（用于测试）
-window.preloaderDebug.restart()
-
-// 显示所有可用的调试命令
-window.preloaderDebug.help()
+```html
+<!-- 由插件在构建时自动注入，路径为真实 chunk hash -->
+<link rel="prefetch" href="/assets/Dashboard-Cx8Kfm3D.js" as="script" crossorigin data-preloader="%2Fdashboard">
+<link rel="prefetch" href="/assets/Charts-DmjPl9Rb.js"    as="script" crossorigin data-preloader="%2Fcharts">
+<link rel="prefetch" href="/assets/Calendar-BnmQ7rKz.js"  as="script" crossorigin data-preloader="%2Fcalendar">
 ```
 
-## 📊 控制台输出示例
-
-### 插件启动日志
-```
-🚀 [预加载插件] 已启用，配置了 3 个路由
-📋 [预加载插件] 路由列表: ["/dashboard", "/calendar", "/charts"]
-⚙️ [预加载插件] 配置选项: { delay: 2000, showStatus: true, statusPosition: "bottom-right", debug: true }
-🎨 [预加载插件] 注入预加载脚本到 HTML
-```
+浏览器会在空闲时自动拉取这些文件到 HTTP 缓存，用户点击路由时直接从缓存加载，无需等待。
 
-### 预加载执行日志
-```
-🚀 [预加载] 开始预加载 3 个页面
-✅ [预加载] /dashboard (156ms) - 自动推断的预加载页面
-✅ [预加载] /calendar (234ms) - 日历组件包含 @fullcalendar 全家桶(~500KB)
-✅ [预加载] /charts (456ms) - 图表页面包含 echarts、@antv/x6 等重型库
-🎉 [预加载] 完成! 耗时 1234ms
-🛠️ 预加载调试工具: window.preloaderDebug
-```
+## ⚙️ 完整配置项
 
-## 🎨 状态显示效果
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `routes` | `(string \| PreloadRoute)[]` | `[]` | 要预加载的路由列表 |
+| `delay` | `number` | `2000` | 状态 UI 延迟显示时间 (ms) |
+| `showStatus` | `boolean` | `true` | 是否显示右下角进度提示 |
+| `statusPosition` | `StatusPosition` | `'bottom-right'` | 进度提示位置 |
+| `debug` | `boolean` | 开发环境 `true` | 开启控制台调试信息 |
+| `exclude` | `string[]` | `[]` | 排除的路由路径（精确或前缀匹配） |
 
-插件会在页面显示优雅的加载状态：
+### `PreloadRoute` 对象格式
 
-```
-🔄 正在优化页面... 2/3
-```
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `path` | `string` | ✅ | 路由路径，含 `:param` 的动态路由会被自动过滤 |
+| `component` | `string` | ❌ | 组件路径，不填自动推断为 `@/views/{path}/index.vue` |
+| `reason` | `string` | ❌ | 备注说明，仅用于调试日志 |
+| `priority` | `number` | ❌ | 优先级，数字越小 `<link>` 越靠前，默认 `2` |
 
-- **位置可配置**：四个角落任选
-- **自动隐藏**：预加载完成后淡出消失
-- **不干扰用户**：`pointer-events: none`，不阻挡交互
+### `StatusPosition` 可选值
 
-## 🔧 最佳实践
+`'bottom-right'` | `'bottom-left'` | `'top-right'` | `'top-left'`
 
-### 1. 路由配置策略
+## 💡 真实使用场景
 
 ```js
-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: '管理后台，权限要求高' }
-]
+preloader({
+  routes: [
+    '/demo/13-calendar',          // 📅 日历组件（fullcalendar）
+    '/demo/29-antv-x6-editor',    // 🎨 流程图编辑器
+    '/demo/16-text-editor',       // 📝 富文本编辑器
+    '/demo/33-v-table-gantt',     // 📊 甘特图组件
+    '/demo/20-dragable',          // 🔄 拖拽组件
+  ],
+  exclude: ['/login', '/404'],
+  delay: 2000,
+  debug: false   // 生产关掉
+})
 ```
 
-### 2. 智能路径推断
+## 🛠️ 调试工具
 
-插件自动将路由路径转换为组件路径：
+**开发环境 `debug: true` 时**，控制台自动输出：
 
-```js
-// 路径推断规则
-'/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. 性能优化建议
-
-```js
-{
-  // ✅ 推荐：给出明确的预加载原因
-  path: '/calendar',
-  reason: '日历组件包含 @fullcalendar(~400KB) + moment.js(~60KB)',
-  priority: 2
-},
-
-{
-  // ✅ 推荐：重型页面单独配置优先级
-  path: '/data-visualization', 
-  reason: '数据可视化包含 d3.js + echarts + three.js (~1.2MB)',
-  priority: 3  // 低优先级，避免影响关键页面
-}
+🚀 vite-plugin-preloader v2
+已注入 3 个 <link rel="prefetch"> 标签（浏览器原生调度）
+✅ /dashboard → /assets/Dashboard-Cx8Kfm3D.js | 主页面，必须快
+✅ /charts    → /assets/Charts-DmjPl9Rb.js    | echarts 太重了
+⚠️  /news/detail/:id (含动态参数，已自动过滤)
 ```
 
-### 4. 开发环境优化
+控制台可用：
 
 ```js
-// vite.config.js
-preloader({
-  routes: [/* ... */],
-  
-  // 开发环境配置
-  ...(process.env.NODE_ENV === 'development' ? {
-    debug: true,        // 开发环境显示详细日志
-    delay: 1000,        // 开发环境快速启动
-    showStatus: true    // 显示状态便于调试
-  } : {
-    debug: false,       // 生产环境静默运行
-    delay: 3000,        // 生产环境延迟更久，确保首屏稳定
-    showStatus: false   // 生产环境不显示状态
-  })
-})
+window.__preloaderDebug.routes          // 查看所有预加载路由及 chunk 路径
+window.__preloaderDebug.check('/charts') // 检查某路由是否已成功映射 chunk
 ```
 
-## 🚀 工作原理
-
-### 构建时
-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) 数据处理复杂的页面。
+```
+构建时（generateBundle hook）：
+  1. 扫描 Rollup/Rolldown bundle → 找到每个组件的输出 chunk 文件名（含 hash）
+  2. 匹配用户配置的路由 → 建立 component 路径 ↔ chunk 文件名 映射
 
-### Q: 开发环境下看不到预加载效果？
-A: 开发环境下模块已经在内存中，预加载效果不明显。可以通过控制台日志确认插件正常工作。
+HTML 处理时（transformIndexHtml hook）：
+  3. 向 </body> 前注入 <link rel="prefetch" href="/assets/Xxx-hash.js">
+  4. 可选：注入状态 UI 脚本（网络感知 + prefetch 事件监听）
 
-### Q: 可以配置生产环境不预加载吗？
-A: 可以。在配置中添加环境判断即可：
-```js
-preloader({
-  routes: process.env.NODE_ENV === 'production' ? [] : ['/dashboard', '/calendar']
-})
+运行时（浏览器）：
+  5. 浏览器解析到 link 标签 → 在空闲时以低优先级 fetch chunk
+  6. 用户点击路由 → Vue Router 触发 import() → 命中浏览器缓存 → 瞬间加载
 ```
 
-## 🤝 贡献
+## 🚨 注意事项
 
-欢迎提交 Issue 和 Pull Request！
+**什么页面适合预加载？**
+- ✅ 用户高频访问的核心页面
+- ✅ 包含大型组件库（echarts / monaco-editor / fullcalendar）的页面
+- ✅ 首屏之后的核心流程页
 
-1. Fork 本仓库
-2. 创建你的特性分支 (`git checkout -b feature/AmazingFeature`)
-3. 提交你的修改 (`git commit -m 'Add some AmazingFeature'`)
-4. 推送到分支 (`git push origin feature/AmazingFeature`)
-5. 开启一个 Pull Request
+**不建议预加载：**
+- ❌ 很少访问的管理页面（浪费带宽）
+- ❌ 需要权限验证的敏感页面（用 `exclude` 排除）
+- ❌ 含 `:param` 的动态详情页（插件会自动过滤）
 
-## 📄 许可证
+## 📋 CHANGELOG
 
-MIT © ChenYu
+### v2.0.0（当前）
+- **[破坏性修复]** 生产环境预加载机制彻底重写：从无效的运行时 `import()` 改为构建时注入 `<link rel="prefetch">`（真实 chunk hash 路径）
+- **[修复]** `configResolved(config)` 正确读取 `@` 别名和项目根目录
+- **[修复]** `routes` 防 `undefined`/非数组崩溃
+- **[修复]** HTML 注入位置从 `</head>` 改为 `</body>` 前
+- **[修复]** 动态路由参数（`:id` 等）自动过滤，不再生成无效 chunk 路径
+- **[新增]** `exclude` 选项，排除不需要预加载的路由
+- **[新增]** `showStatus` / `statusPosition` 完整实现（之前仅文档声明未实现）
+- **[新增]** 网络感知：省流模式 / 2G 网络下自动跳过状态 UI
+- **[新增]** SSR 构建自动跳过（`isSsrBuild` 检测）
+- **[升级]** peerDependencies 支持 Vite 8，移除无用的 `vue` peerDep
+- **[升级]** TypeScript 类型定义与实现完全对齐
 
----
+### v1.1.x（历史）
+- 早期版本，使用运行时动态 `import()` 预加载方式，开创了按优先级精细化路由预加载的配置模式
 
-**🎯 一行配置，极致性能！让你的 Vue 应用飞起来！** 🚀

package/dist/index.d.mts

@@ -1,17 +1,50 @@
 import { Plugin } from 'vite';
 
 interface PreloadRoute {
+    /** 路由路径，如 /dashboard。含 :param 的动态路由会被自动过滤 */
     path: string;
+    /** 可选。组件文件路径，不填则自动推断为 @/views/{path}/index.vue */
     component?: string;
+    /** 备注说明，仅用于日志显示 */
     reason?: string;
+    /** 优先级，数字越小越优先加载，默认 2 */
     priority?: number;
 }
+type StatusPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
 interface PreloaderOptions {
-    routes: (string | PreloadRoute)[];
+    /**
+     * 要预加载的路由列表，支持字符串或对象格式
+     * 含 :param 的动态路由段会被自动过滤
+     * 默认 []
+     */
+    routes?: (string | PreloadRoute)[];
+    /**
+     * 页面加载完成后延迟多少毫秒再触发状态显示
+     * 默认 2000ms
+     */
     delay?: number;
+    /**
+     * 是否开启调试日志与 window.__preloaderDebug 调试工具
+     * 默认：开发环境 true，生产环境 false
+     */
     debug?: boolean;
+    /**
+     * 是否在页面角落显示预加载状态提示
+     * 默认 true
+     */
+    showStatus?: boolean;
+    /**
+     * 状态提示的显示位置
+     * 默认 'bottom-right'
+     */
+    statusPosition?: StatusPosition;
+    /**
+     * 要排除预加载的路由路径列表（精确匹配或前缀匹配）
+     * 例：['/404', '/login', '/admin']
+     */
+    exclude?: string[];
 }
 
-declare function preloaderPlugin(options: PreloaderOptions): Plugin;
+declare function preloaderPlugin(userOptions?: PreloaderOptions): Plugin;
 
-export { type PreloadRoute, type PreloaderOptions, preloaderPlugin as default };
+export { type PreloadRoute, type PreloaderOptions, type StatusPosition, preloaderPlugin as default };

package/dist/index.d.ts

@@ -1,17 +1,50 @@
 import { Plugin } from 'vite';
 
 interface PreloadRoute {
+    /** 路由路径，如 /dashboard。含 :param 的动态路由会被自动过滤 */
     path: string;
+    /** 可选。组件文件路径，不填则自动推断为 @/views/{path}/index.vue */
     component?: string;
+    /** 备注说明，仅用于日志显示 */
     reason?: string;
+    /** 优先级，数字越小越优先加载，默认 2 */
     priority?: number;
 }
+type StatusPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
 interface PreloaderOptions {
-    routes: (string | PreloadRoute)[];
+    /**
+     * 要预加载的路由列表，支持字符串或对象格式
+     * 含 :param 的动态路由段会被自动过滤
+     * 默认 []
+     */
+    routes?: (string | PreloadRoute)[];
+    /**
+     * 页面加载完成后延迟多少毫秒再触发状态显示
+     * 默认 2000ms
+     */
     delay?: number;
+    /**
+     * 是否开启调试日志与 window.__preloaderDebug 调试工具
+     * 默认：开发环境 true，生产环境 false
+     */
     debug?: boolean;
+    /**
+     * 是否在页面角落显示预加载状态提示
+     * 默认 true
+     */
+    showStatus?: boolean;
+    /**
+     * 状态提示的显示位置
+     * 默认 'bottom-right'
+     */
+    statusPosition?: StatusPosition;
+    /**
+     * 要排除预加载的路由路径列表（精确匹配或前缀匹配）
+     * 例：['/404', '/login', '/admin']
+     */
+    exclude?: string[];
 }
 
-declare function preloaderPlugin(options: PreloaderOptions): Plugin;
+declare function preloaderPlugin(userOptions?: PreloaderOptions): Plugin;
 
-export { type PreloadRoute, type PreloaderOptions, preloaderPlugin as default };
+export { type PreloadRoute, type PreloaderOptions, type StatusPosition, preloaderPlugin as default };