Sunbelt Computer Software

Build Version Tracker

一个通用的构建工具插件，用于版本跟踪和构建自动化（支持 Webpack 3.0+ 和 Vite）。

功能特性

📦 自动生成构建版本信息
🔍 记录构建人、分支和时间
📄 生成版本文件 (version.txt)
🗜️ 自动打包构建产物为 ZIP 文件
🌐 插件完全通过配置参数控制行为，不依赖环境变量
⚡ 同时支持 Webpack (3.0+) 和 Vite 构建工具
🔧 支持 ES 模块和 CommonJS 模块
🛠️ 智能版本检测，自动适配不同 Webpack 版本
✨ 支持自定义版本信息格式化

安装

基本安装

npm install build-version-tracker
# 或
pnpm add build-version-tracker
# 或
yarn add build-version-tracker

依赖安装

插件需要以下依赖才能正常工作，请根据您的使用场景安装：

如果使用 Webpack 插件：

npm install adm-zip webpack
# 或
pnpm add adm-zip webpack
# 或
yarn add adm-zip webpack

如果使用 Vite 插件：

npm install adm-zip
# 或
pnpm add adm-zip
# 或
yarn add adm-zip

一次性安装所有依赖：

npm install build-version-tracker adm-zip webpack
# 或
pnpm add build-version-tracker adm-zip webpack
# 或
yarn add build-version-tracker adm-zip webpack

本地开发测试

使用 npm link 进行本地测试

如果您想在本地其他项目中测试该插件，可以使用 npm link 方法：

1. 在插件项目中创建全局链接

# 进入插件项目目录
cd build-version-tracker

# 构建插件
npm run build

# 创建全局链接
npm link

2. 在测试项目中链接插件

# 进入测试项目目录
cd /path/to/your/test-project

# 链接插件
npm link build-version-tracker

# 安装插件的 peerDependencies
npm install adm-zip webpack

3. 在测试项目中使用插件

// Webpack 配置示例
const BuildVersionTracker = require('build-version-tracker');

module.exports = {
  // ... 其他配置
  plugins: [
    new BuildVersionTracker({
      distPath: 'dist',
      isBuild: true
    })
  ]
};

4. 取消链接（测试完成后）

# 在测试项目中取消链接
npm unlink build-version-tracker

# 重新安装正式版本（如果需要）
npm install build-version-tracker

# 在插件项目中取消全局链接
cd build-version-tracker
npm unlink

使用 pnpm link（如果使用 pnpm）

# 在插件项目中
pnpm link --global

# 在测试项目中
pnpm link build-version-tracker

使用 yarn link（如果使用 yarn）

# 在插件项目中
yarn link

# 在测试项目中
yarn link build-version-tracker

使用方法

Webpack 插件使用

CommonJS 语法

const BuildVersionTracker = require('build-version-tracker');

module.exports = {
  // ... 其他配置
  plugins: [
    new BuildVersionTracker({
      distPath: 'dist',     // 构建输出目录，默认 'dist'
      isBuild: false,      // 是否启用构建，默认 false
      htmlName: 'index.html', // HTML 文件名，默认 'index.html'
      // 自定义版本信息格式化
      formatVersion: (info) => {
        return `Version: ${info.time}, Branch: ${info.currentBranch}, User: ${info.userName}`;
      },
      // 自定义文本版本信息格式化
      formatTextVersion: (info) => {
        return `Build: ${info.time}, Branch: ${info.currentBranch}, By: ${info.userName}, Path: ${info.distPath}`;
      }
    })
  ]
};

ES 模块语法

import BuildVersionTracker from 'build-version-tracker';

export default {
  // ... 其他配置
  plugins: [
    new BuildVersionTracker({
      distPath: 'dist',
      isBuild: false,
      htmlName: 'index.html',
      // 自定义版本信息格式化
      formatVersion: (info) => {
        return `Version: ${info.time}, Branch: ${info.currentBranch}, User: ${info.userName}`;
      },
      // 自定义文本版本信息格式化
      formatTextVersion: (info) => {
        return `Build: ${info.time}, Branch: ${info.currentBranch}, By: ${info.userName}`;
      }
    })
  ]
};

Vite 插件使用

CommonJS 语法

const viteVersionPlugin = require('build-version-tracker/vite');

export default {
  plugins: [
    viteVersionPlugin({
      distPath: 'dist',     // 构建输出目录，默认 'dist'
      isBuild: false,      // 是否启用构建，默认 false
      htmlName: 'index.html', // HTML 文件名，默认 'index.html'
      // 自定义版本信息格式化
      formatVersion: (info) => {
        return `Version: ${info.time}, Branch: ${info.currentBranch}, User: ${info.userName}`;
      },
      // 自定义文本版本信息格式化
      formatTextVersion: (info) => {
        return `Build: ${info.time}, Branch: ${info.currentBranch}, By: ${info.userName}`;
      }
    })
  ]
};

ES 模块语法

import viteVersionPlugin from 'build-version-tracker/vite';

export default {
  plugins: [
    viteVersionPlugin({
      distPath: 'dist',
      isBuild: false,
      htmlName: 'index.html',
      // 自定义版本信息格式化
      formatVersion: (info) => {
        return `Version: ${info.time}, Branch: ${info.currentBranch}, User: ${info.userName}`;
      },
      // 自定义文本版本信息格式化
      formatTextVersion: (info) => {
        return `Build: ${info.time}, Branch: ${info.currentBranch}, By: ${info.userName}`;
      }
    })
  ]
};

配置说明

插件完全通过配置参数控制行为，不依赖环境变量。

插件生命周期

Webpack 插件

Webpack 3.x: 使用 plugin('after-emit') 方法
Webpack 4+: 使用 hooks.afterEmit.tapAsync() 方法
Webpack 5+: 使用 hooks.afterEmit.tapAsync() 方法（新钩子系统）
智能版本检测，自动适配不同 Webpack 版本

Vite 插件

使用 closeBundle 钩子，确保在所有构建操作完成后执行版本信息生成
避免使用 buildEnd 钩子，防止文件被后续构建步骤覆盖

示例

Webpack 基础使用

// webpack.config.js
const BuildVersionTracker = require('build-version-tracker');

module.exports = {
  mode: 'production',
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js'
  },
  plugins: [
    new BuildVersionTracker()
  ]
};

Vite 基础使用

// vite.config.js
import viteVersionPlugin from 'build-version-tracker/vite';

export default {
  plugins: [
    viteVersionPlugin()
  ],
  build: {
    outDir: 'dist'
  }
};

自定义配置

// Webpack 自定义配置
new BuildVersionTracker({
  distPath: 'build',                    // 自定义输出目录
  isBuild: true,                        // 启用构建功能
  htmlName: 'app.html',                  // 自定义 HTML 文件名
  // 自定义版本信息格式化
  formatVersion: (info) => {
    return `Build: ${info.time}, Branch: ${info.currentBranch}, By: ${info.userName}`;
  }
})

// Vite 自定义配置
viteVersionPlugin({
  distPath: 'build',
  isBuild: true,                        // 启用构建功能
  htmlName: 'app.html',
  // 自定义版本信息格式化
  formatVersion: (info) => {
    return `Build: ${info.time}, Branch: ${info.currentBranch}, By: ${info.userName}`;
  }
})

// 明确配置构建参数（推荐方式）
new BuildVersionTracker({
  distPath: 'dist',        // 明确指定输出目录
  isBuild: true,           // 明确控制构建行为
  htmlName: 'index.html',
  // 自定义版本信息格式化
  formatVersion: (info) => {
    return `Version: ${info.time}, Branch: ${info.currentBranch}, User: ${info.userName}`;
  }
})

输出文件

插件会在构建完成后生成以下文件：

version.txt: 包含构建信息的文本文件
dist.zip: 构建产物的压缩包
HTML 文件更新: 在 body 标签后插入版本信息脚本

version.txt 内容示例

构建人： username, 构建分支：main, 构建时间：2024-01-01 12:00:00，构建后文件位于：dist

自定义格式示例

Version: 2024-01-01 12:00:00, Branch: main, User: username

HTML 文件更新示例

构建后，HTML 文件会在 </body> 标签前插入版本信息脚本：

<script>console.log("%c构建人： username, 构建分支：main, 构建时间：2024-01-01 12:00:00", 'color:blue')</script>
</body>

API

Webpack 插件选项

参数	类型	默认值	描述
distPath	string	'dist'	构建输出目录
isBuild	boolean	false	是否启用构建功能
htmlName	string	'index.html'	HTML 文件名
formatVersion	function	null	自定义版本信息格式化函数
formatTextVersion	function	null	自定义文本版本信息格式化函数

Vite 插件选项

参数	类型	默认值	描述
distPath	string	'dist'	构建输出目录
isBuild	boolean	false	是否启用构建功能
htmlName	string	'index.html'	HTML 文件名
formatVersion	function	null	自定义版本信息格式化函数
formatTextVersion	function	null	自定义文本版本信息格式化函数

自定义格式化函数参数

开发

项目结构

src/
├── index.js          # Webpack 插件实现（支持 3.0+）
├── vite-plugin.js    # Vite 插件实现
└── utils.js          # 公共工具函数

构建项目

pnpm run build
# 或
npm run build

运行测试

pnpm test
# 或
npm test

技术实现

版本检测机制

插件使用智能版本检测机制，自动适配不同版本的 Webpack：

Webpack 4+: 从 compiler.webpack.version 获取版本信息
Webpack 3.x: 从 compiler.version 获取版本信息
降级策略: 通过检测钩子系统存在性推断版本

钩子系统适配

Webpack 3.x: 使用 compiler.plugin('after-emit')
Webpack 4+: 使用 compiler.hooks.afterEmit.tapAsync()
Vite: 使用 closeBundle 钩子确保构建完成后执行

错误处理

插件包含完善的错误处理机制，确保在各种情况下都能优雅降级：

版本检测失败时使用默认版本
钩子系统不存在时提供详细警告
构建过程中的错误会被捕获并记录

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！

提交 Issue: GitHub Issues
提交 Pull Request: GitHub Pull Requests
项目仓库: GitHub Repository

更新日志

v0.0.4

初始版本发布
支持 Webpack (3.0+) 和 Vite 构建工具
支持 ES 模块和 CommonJS 模块
自动生成版本信息和打包构建产物
智能版本检测，自动适配不同 Webpack 版本
完善的错误处理和降级策略
优化测试脚本，支持 ES 模块语法
✨ 支持自定义版本信息格式化

v0.0.3

初始版本发布
支持 Webpack (3.0+) 和 Vite 构建工具
支持 ES 模块和 CommonJS 模块
自动生成版本信息和打包构建产物
智能版本检测，自动适配不同 Webpack 版本
完善的错误处理和降级策略
✨优化测试脚本，支持 ES 模块语法

v0.0.2

初始版本发布
✨ 支持 Webpack (3.0+) 和 Vite 构建工具
支持 ES 模块和 CommonJS 模块
自动生成版本信息和打包构建产物
✨ 智能版本检测，自动适配不同 Webpack 版本
✨ 完善的错误处理和降级策略

v0.0.1

初始版本发布
支持 Webpack 和 Vite 构建工具
支持 ES 模块和 CommonJS 模块
自动生成版本信息和打包构建产物

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.github/workflows		.github/workflows
src		src
test		test
.gitignore		.gitignore
.npmignore		.npmignore
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
vite.config.js		vite.config.js

参数	类型	描述
userName	string	构建人
currentBranch	string	构建分支
time	string	构建时间
distPath	string	构建产物路径

Sunbelt Computer Software

PL/B Language Development and Support

Folders and files

Latest commit

History

Repository files navigation

Build Version Tracker

功能特性

安装

基本安装

依赖安装

如果使用 Webpack 插件：

如果使用 Vite 插件：

一次性安装所有依赖：

本地开发测试

使用 npm link 进行本地测试

1. 在插件项目中创建全局链接

2. 在测试项目中链接插件

3. 在测试项目中使用插件

4. 取消链接（测试完成后）

使用 pnpm link（如果使用 pnpm）

使用 yarn link（如果使用 yarn）

使用方法

Webpack 插件使用

CommonJS 语法

ES 模块语法

Vite 插件使用

CommonJS 语法

ES 模块语法

配置说明

插件生命周期

Webpack 插件

Vite 插件

示例

Webpack 基础使用

Vite 基础使用

自定义配置

输出文件

version.txt 内容示例

自定义格式示例

HTML 文件更新示例

API

Webpack 插件选项

Vite 插件选项

自定义格式化函数参数

开发

项目结构

构建项目

运行测试

技术实现

版本检测机制

钩子系统适配

错误处理

许可证

贡献

更新日志

v0.0.4

v0.0.3

v0.0.2

v0.0.1

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages