universal-build-plugin-version-check-test/README.md

一个支持多种前端构建工具的通用插件框架，包括 Vite、Webpack、Rollup 等，提供版本检查、构建优化等功能

# Universal Build Plugin

一个支持多种前端构建工具的通用插件框架，包括 Vite、Webpack、Rollup 等。

## 特性

- 🚀 **多构建工具支持**: 支持 Vite、Webpack、Rollup
- 📦 **TypeScript 支持**: 完整的 TypeScript 类型定义
- 🔧 **可扩展架构**: 基于抽象类的插件架构，易于扩展
- 📋 **版本管理**: 自动生成版本信息文件，包含构建时间、Git 信息等
- 🧪 **完整测试**: 包含完整的单元测试
- 📝 **详细文档**: 提供详细的 API 文档和使用示例

## 安装

```bash
npm install universal-build-plugin
# 或
yarn add universal-build-plugin
# 或
pnpm add universal-build-plugin
```

## 快速开始

### Vite 项目

```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import { VitePlugin } from 'universal-build-plugin';

export default defineConfig({
  plugins: [
    new VitePlugin({
      name: 'my-plugin',
      debug: true,
      generateVersionFile: true, // 启用版本文件生成
    }).apply(),
  ],
});
```

### Webpack 项目

```typescript
// webpack.config.js
const { WebpackPlugin } = require('universal-build-plugin');

module.exports = {
  plugins: [
    new WebpackPlugin({
      name: 'my-plugin',
      debug: true,
    }),
  ],
};
```

### Rollup 项目

```typescript
// rollup.config.js
import { RollupPlugin } from 'universal-build-plugin';

export default {
  plugins: [
    new RollupPlugin({
      name: 'my-plugin',
      debug: true,
    }).apply(),
  ],
};
```

## API 文档

### PluginOptions

插件配置选项接口：

```typescript
interface PluginOptions {
  /** 插件名称 */
  name?: string;
  /** 是否启用调试模式 */
  debug?: boolean;
  /** 是否生成版本文件 */
  generateVersionFile?: boolean;
  /** 自定义配置选项 */
  [key: string]: any;
}
```

### BasePlugin

所有插件的基类，提供通用功能：

```typescript
abstract class BasePlugin {
  constructor(options: PluginOptions);
  abstract apply(context: BuildContext): any;
  protected onBuildStart(context: BuildContext): Promise<void>;
  protected onBuildEnd(context: BuildContext): Promise<void>;
  protected onFileChanged(filePath: string, context: BuildContext): Promise<void>;
}
```

## 版本管理功能

插件会在构建完成后自动在项目根目录生成 `version.json` 文件，包含以下信息：

```json
{
  "version": "1.0.0",
  "buildTime": "2024-08-07T10:30:00.000Z",
  "bundler": "vite",
  "mode": "production",
  "gitCommit": "a1b2c3d4",
  "gitBranch": "main",
  "environment": "production",
  "projectName": "my-project",
  "buildNumber": 42
}
```

### 启用版本管理

```typescript
// 默认启用（使用 package.json 版本）
new VitePlugin({
  generateVersionFile: true, // 默认为 true
}).apply()

// 禁用版本管理
new VitePlugin({
  generateVersionFile: false,
}).apply()
```

### 自定义版本生成方式

插件支持多种版本生成方式：

#### 1. Git Hash 版本
```typescript
new VitePlugin({
  generateVersionFile: true,
  versionInfo: {
    versionType: 'git-hash',
    meta: {
      buildBy: 'CI/CD',
      environment: 'production',
    },
  },
}).apply()
```

#### 2. 时间戳版本
```typescript
new VitePlugin({
  generateVersionFile: true,
  versionInfo: {
    versionType: 'timestamp',
    meta: {
      buildServer: 'jenkins-01',
    },
  },
}).apply()
```

#### 3. 自定义版本（支持异步）
```typescript
new VitePlugin({
  generateVersionFile: true,
  versionInfo: {
    versionType: 'custom',
    customVersion: async () => {
      // 支持异步操作
      const apiResponse = await fetch('/api/version');
      const data = await apiResponse.json();
      return `v${data.major}.${data.minor}.${data.patch}`;
    },
    meta: {
      buildType: 'api-generated',
    },
  },
}).apply()
```

### 手动使用版本管理

```typescript
import { VersionManager } from 'universal-build-plugin';

const versionManager = new VersionManager();

// 生成版本信息
const versionInfo = await versionManager.generateVersionInfo('vite', 'production');

// 写入版本文件
await versionManager.writeVersionFile(versionInfo);

// 读取现有版本文件
const existingVersion = await versionManager.readVersionFile();
```

## 自定义插件开发

### 创建自定义 Vite 插件

```typescript
import { VitePlugin } from 'universal-build-plugin';

class MyVitePlugin extends VitePlugin {
  protected shouldTransform(id: string): boolean {
    return id.endsWith('.special');
  }

  protected async transformCode(code: string, id: string, context: BuildContext): Promise<string> {
    // 自定义代码转换逻辑
    return `// Transformed by MyVitePlugin\n${code}`;
  }
}

// 使用
export default defineConfig({
  plugins: [
    new MyVitePlugin({ name: 'my-special-plugin' }).apply(),
  ],
});
```

### 创建自定义 Webpack 插件

```typescript
import { WebpackPlugin } from 'universal-build-plugin';

class MyWebpackPlugin extends WebpackPlugin {
  protected async processAssets(assets: Array<{ name: string; source: any }>, context: BuildContext): Promise<void> {
    // 自定义资源处理逻辑
    console.log(`Processing ${assets.length} assets`);
  }
}

// 使用
module.exports = {
  plugins: [
    new MyWebpackPlugin({ name: 'my-webpack-plugin' }),
  ],
};
```

## 开发

### 安装依赖

```bash
npm install
```

### 构建

```bash
npm run build
```

### 测试

```bash
npm test
```

### 代码检查

```bash
npm run lint
```

### 格式化代码

```bash
npm run format
```

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

MIT License