Webpack Version Plugin

一个 Webpack 插件，在打包时根据 git 分支名称和时间自动生成版本号。

功能特性

• 根据 git 分支名称生成版本号
• 支持自定义版本号格式
• 自动生成 version.json 文件供前端读取
• 支持注入全局变量到代码中
• 支持获取 git commit hash
• 检测是否有未提交的更改 (dirty state)

安装

npm install --save-dev @ruan-feiyang/webpack-version-plugin

或者直接复制 WebpackVersionPlugin.js 到你的项目。

使用方法

基础用法

const WebpackVersionPlugin = require('@ruan-feiyang/webpack-version-plugin');

module.exports = {
  // ...
  plugins: [
    new WebpackVersionPlugin()
  ]
};

完整配置

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)

{
  "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 |

前端读取版本号

方式一：通过全局变量

console.log(__APP_VERSION__.version);  // main-20260407-133045-abc123
console.log(__APP_VERSION__.branch);    // main
console.log(__APP_VERSION__.hash);      // abc123

方式二：通过 JSON 文件

fetch('/version.json')
  .then(res => res.json())
  .then(data => {
    console.log(data.version);
    console.log(data.buildTime);
  });

方式三：通过环境变量

// 在 HTML 中注入
<script>
  window.APP_VERSION = '__APP_VERSION__';
</script>

方式四：通过控制台别名

启用 consoleAlias 后，可以在浏览器控制台直接输入别名访问版本信息：

// 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