vite-plugin-trae-image-preloader/README.md

Vite plugin for preloading images in development mode

# Vite Plugin Image Preloader

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

## 安装

```bash
pnpm add vite-plugin-trae-image-preloader
```

## 使用方法

### ESM 导入方式（推荐）

```typescript
// 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 导入方式

```javascript
// 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'
    })
  ]
})
```

### 混合导入方式

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

// 方式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')
```

## 配置选项

```typescript
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. 检查导入方式

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

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

### 3. 调试模式

启用详细日志：
```typescript
imagePreloader({
  verbose: true  // 查看详细的加载过程
})
```

### 4. 全局调试接口

在浏览器控制台使用：
```javascript
// 查看发现的图片
window.__imagePreloader.imageUrls

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

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

## 示例项目

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

## License

MIT