Vite Plugin Image Preloader

智能图片预加载插件，支持 React 和 Vue 框架，具备301重定向处理和后台轮询功能。

安装

pnpm add vite-plugin-trae-image-preloader

使用方法

ESM 导入方式（推荐）

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

export default defineConfig({
  plugins: [
    imagePreloader({
      verbose: true,
      framework: 'react', // 或 'vue' 或 'auto'
      devOnly: true
    })
  ]
})

CommonJS 导入方式

// vite.config.js
const { defineConfig } = require('vite')
const imagePreloader = require('vite-plugin-trae-image-preloader').default

module.exports = defineConfig({
  plugins: [
    imagePreloader({
      verbose: true,
      framework: 'auto'
    })
  ]
})

混合导入方式

// 如果遇到导入问题，可以尝试这些方式：

// 方式1：默认导入
import imagePreloader from 'vite-plugin-trae-image-preloader'

// 方式2：require 默认导出
const imagePreloader = require('vite-plugin-trae-image-preloader').default

// 方式3：动态导入
const { default: imagePreloader } = await import('vite-plugin-trae-image-preloader')

配置选项

interface ImagePreloaderOptions {
  extensions?: string[]    // 支持的图片扩展名，默认: ['png', 'jpg', 'jpeg', 'gif', 'svg', 'webp', 'avif']
  verbose?: boolean        // 是否显示详细日志，默认: true
  framework?: 'auto' | 'react' | 'vue' | 'vanilla'  // 框架类型，默认: 'auto'
  devOnly?: boolean        // 仅在开发模式下工作，默认: true
  delay?: number          // 预加载延迟（毫秒），默认: 1000
}

功能特性

• ✅ 智能代码扫描：分析代码中的图片引用，无需文件系统扫描
• ✅ HTTP API 支持：支持动态API图片URL
• ✅ 301重定向处理：检测默认图片，后台轮询真实图片
• ✅ 分批加载：每批5张图片，间隔3秒，避免服务器压力
• ✅ 自动图片更新：获取真实图片后自动替换页面中的默认图片
• ✅ 框架自动检测：支持 React、Vue 和原生项目
• ✅ 调试接口：window.__imagePreloader 全局调试对象

排查问题

1. 检查插件是否正确加载

在浏览器控制台查看是否有以下日志：

🖼️ Image Preloader Plugin enabled for react
🖼️ Found X image(s) in YourComponent.tsx

2. 检查导入方式

如果插件没有输出，可能是导入方式问题：

// 尝试不同的导入方式
import imagePreloader from 'vite-plugin-trae-image-preloader'  // ESM
const imagePreloader = require('vite-plugin-trae-image-preloader')  // CJS (可能需要 .default)

3. 调试模式

启用详细日志：

imagePreloader({
  verbose: true  // 查看详细的加载过程
})

4. 全局调试接口

在浏览器控制台使用：

// 查看发现的图片
window.__imagePreloader.imageUrls

// 手动触发预加载
window.__imagePreloader.preloadAllImages()

// 查看已加载的图片
window.__imagePreloader.getPreloadedImages()

示例项目

参见 packages/demo 目录中的完整示例。

License

MIT