npm package: @ruan-feiyang/webpack-version-plugin
Description: Webpack plugin to generate version based on git branch and timestamp
Latest version: 1.0.1

# Webpack Version Plugin

一个 Webpack 插件，在打包时根据 git 分支名称和时间自动生成版本号。

## 功能特性

- 根据 git 分支名称生成版本号
- 支持自定义版本号格式
- 自动生成 version.json 文件供前端读取
- 支持注入全局变量到代码中
- 支持获取 git commit hash
- 检测是否有未提交的更改 (dirty state)

## 安装

```bash
npm install --save-dev @ruan-feiyang/webpack-version-plugin
```

或者直接复制 `WebpackVersionPlugin.js` 到你的项目。

## 使用方法

### 基础用法

```javascript
const WebpackVersionPlugin = require('@ruan-feiyang/webpack-version-plugin');

module.exports = {
  // ...
  plugins: [
    new WebpackVersionPlugin()
  ]
};
```

### 完整配置

```javascript
const WebpackVersionPlugin = require('@ruan-feiyang/webpack-version-plugin');

module.exports = {
  plugins: [
    new WebpackVersionPlugin({
      // 输出文件名 (默认: version.json)
      filename: 'version.json',
      
      // 是否在控制台输出版本信息 (默认: true)
      verbose: true,
      
      // 版本号格式
      // 可用占位符:
      //   {branch}   - git 分支名称
      //   {date}     - 日期 (YYYYMMDD)
      //   {time}     - 时间 (HHMMSS)
      //   {datetime} - 日期时间 (YYYYMMDD-HHMMSS)
      //   {hash}     - git commit hash (短)
      //   {fullhash} - git commit hash (完整)
      //   {dirty}    - 未提交状态 (-dirty)
      //   {timestamp}- Unix 时间戳
      format: '{branch}-{datetime}-{hash}',
      
      // hash 长度 (默认: 6)
      hashLength: 6,
      
      // 全局变量名 (默认: __VERSION__)
      variableName: '__APP_VERSION__',
      
      // 是否注入全局变量 (默认: true)
      injectVariable: true,
      
      // 控制台别名，设为 false 禁用，设为字符串则使用该字符串作为别名 (默认: 'version')
      // 例如设置为 'version'，则可以在控制台直接输入 version 访问
      consoleAlias: 'version',
      
      // 是否写入版本文件 (默认: true)
      writeFile: true,
      
      // 自定义文件输出目录 (默认: output.path)
      outputPath: './dist',
      
      // 额外信息
      extra: {
        author: 'feiyang',
        buildNumber: process.env.BUILD_NUMBER || 1
      }
    })
  ]
};
```

## 输出示例

### 版本文件 (version.json)

```json
{
  "version": "main-20260407-133045-abc123",
  "branch": "main",
  "hash": "abc123",
  "fullHash": "abc123def456...",
  "dirty": false,
  "datetime": "2026-04-07T13:30:45.123Z",
  "timestamp": 1744006845123,
  "format": "{branch}-{datetime}-{hash}",
  "author": "Your Name",
  "buildNumber": 1
}
```

### 生成的版本号

| 分支 | 格式 | 输出示例 |
|------|------|---------|
| main | `{branch}-{hash}` | `main-abc123` |
| main | `{branch}-{datetime}` | `main-20260407-133045` |
| main | `{branch}-{datetime}-{hash}` | `main-20260407-133045-abc123` |
| feature/login | `{branch}-{hash}` | `feature-login-abc123` |
| develop | `v{date}.{hash}` | `v20260407.abc123` |

## 前端读取版本号

### 方式一：通过全局变量

```javascript
console.log(__APP_VERSION__.version);  // main-20260407-133045-abc123
console.log(__APP_VERSION__.branch);    // main
console.log(__APP_VERSION__.hash);      // abc123
```

### 方式二：通过 JSON 文件

```javascript
fetch('/version.json')
  .then(res => res.json())
  .then(data => {
    console.log(data.version);
    console.log(data.buildTime);
  });
```

### 方式三：通过环境变量

```javascript
// 在 HTML 中注入
<script>
  window.APP_VERSION = '__APP_VERSION__';
</script>
```

### 方式四：通过控制台别名

启用 `consoleAlias` 后，可以在浏览器控制台直接输入别名访问版本信息：

```javascript
// webpack.config.js 配置
new WebpackVersionPlugin({
  consoleAlias: 'version'  // 启用控制台别名
})

// 在浏览器控制台输入:
version        // 返回完整版本信息对象
version.branch // 返回分支名
version.hash   // 返回 hash
```

## API

### `new WebpackVersionPlugin(options)`

创建插件实例。

#### Options

| 选项 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `filename` | `string` | `'version.json'` | 输出文件名 |
| `verbose` | `boolean` | `true` | 是否输出详细信息 |
| `format` | `string` | `'{branch}-{datetime}-{hash}'` | 版本号格式 |
| `hashLength` | `number` | `6` | hash 长度 |
| `variableName` | `string` | `'__VERSION__'` | 全局变量名 |
| `injectVariable` | `boolean` | `true` | 是否注入全局变量 |
| `consoleAlias` | `string \| boolean` | `'version'` | 控制台别名，设为 `false` 禁用 |
| `writeFile` | `boolean` | `true` | 是否写入文件 |
| `outputPath` | `string` | `output.path` | 输出目录 |
| `extra` | `object` | `{}` | 额外的信息 |

## 版本号格式说明

```
{branch}   → git 分支名 (特殊字符会被替换为 -)
{date}     → 日期 YYYYMMDD
{time}     → 时间 HHMMSS
{datetime} → 日期时间 YYYYMMDD-HHMMSS
{hash}     → 短 hash (默认6位)
{fullhash} → 完整 hash
{dirty}    → 未提交状态 (-dirty)
{timestamp}→ Unix 时间戳
```

## License

MIT