build-version-json

Webpack / Vite 构建完成后向输出目录写入 version.json，配合前端轮询实现「部署后提示用户刷新」。

安装

npm install --save-dev build-version-json

Webpack 用法（Vue CLI）

// vue.config.js
const { BuildVersionWebpackPlugin } = require('build-version-json');
// 或按需引入：require('build-version-json/webpack')

module.exports = {
  outputDir: 'dist',
  configureWebpack: {
    plugins: [
      new BuildVersionWebpackPlugin({
        rootDir: __dirname,
        outputDir: 'dist',
      }),
    ],
  },
};

Vite 用法

// vite.config.js
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { buildVersionVitePlugin } from 'build-version-json';
// 或按需引入：import buildVersionVitePlugin from 'build-version-json/vite'

export default defineConfig({
  plugins: [
    vue(),
    buildVersionVitePlugin({
      rootDir: process.cwd(),
      outputDir: 'dist',
    }),
  ],
});

TypeScript 项目用法

包已内置类型声明，可直接在 vite.config.ts、vue.config.ts 及前端 TS 代码中使用。

Vite + TypeScript

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { buildVersionVitePlugin } from 'build-version-json';
import type { BuildVersionOptions } from 'build-version-json';

const versionOptions: BuildVersionOptions = {
  rootDir: process.cwd(),
  outputDir: 'dist',
};

export default defineConfig({
  plugins: [vue(), buildVersionVitePlugin(versionOptions)],
});

Vue CLI + TypeScript（vue.config.ts）

若项目根目录存在 vue.config.ts，需额外安装 @types/webpack：

npm install --save-dev @types/webpack

// vue.config.ts
import path from 'node:path';
import { defineConfig } from '@vue/cli-service';
import { BuildVersionWebpackPlugin } from 'build-version-json';

export default defineConfig({
  configureWebpack: {
    plugins: [
      new BuildVersionWebpackPlugin({
        rootDir: __dirname,
        outputDir: 'dist',
      }),
    ],
  },
});

仍使用 vue.config.js 的 JavaScript 项目无需改动，类型声明为可选增强。

前端 autoUpdate（TypeScript）

import autoUpdate, { type AutoUpdateOptions } from 'build-version-json/client';

const options: AutoUpdateOptions = {
  allowedHosts: ['localhost', 'your-domain.com'],
};

autoUpdate.start(options);

window.addEventListener('onmessageUpdate', (event) => {
  console.log(event.detail.msg, event.detail.version);
});

环境变量开关

| 变量 | 说明 | | ------ | ------ | | VUE_BUILD_NOTIFY=true | Vue CLI / Webpack 项目 | | VITE_BUILD_NOTIFY=true | Vite 项目（.env.production） | | BUILD_VERSION_NOTIFY=true | 通用环境变量 | | npm run build --notify | 通过 npm_config_notify 临时开启 |

关闭：npm run build --notify=false 或设置变量为 false / 0。

分支与提交人（加密 meta）

配置共享密钥后，构建产物会额外写入加密字段 meta（AES-256-GCM）：

| 变量 | 说明 | | ------ | ------ | | BUILD_VERSION_META_SECRET | meta 加密密钥（与监控页 monitor-meta-config.php 一致） | | BUILD_VERSION_BRANCH | 可选，覆盖 Git 分支名 | | BUILD_VERSION_AUTHOR | 可选，覆盖 Git 最后提交人（默认 git log -1 --format=%an） | | BUILD_VERSION_PACKER | 可选，覆盖打包人（默认 git config user.name） |

{
  "version": "1723872000123",
  "meta": "v1:Base64IvCipherTag..."
}

未配置密钥时行为与旧版一致，仅写入 { "version": "..." }。

插件选项

| 选项 | 类型 | 默认值 | 说明 | | ------ | ------ | -------- | ------ | | rootDir | string | process.cwd() | 项目根目录 | | outputDir | string | 构建工具输出路径 | 写入 version.json 的目录 | | filename | string | version.json | 版本文件名 | | publicVersionPath | string | public/version.json | 构建前 public 下的版本文件路径 | | cleanupPublic | boolean | true | 构建成功后删除 public 下的 version.json | | enabled | boolean | 读环境变量 | 强制开关 | | generateVersion | function | Date.now() | 自定义版本号 | | formatContent | function | { version } | 自定义 JSON 内容 | | includeMeta | boolean | 有密钥时 true | 是否写入加密 meta（分支/提交人） | | metaSecret | string | 读环境变量 | meta 加密密钥，与监控页解密配置一致 | | collectBuildMeta | function | Git 采集 | 自定义分支/提交人采集 | | log | boolean | true | 是否输出日志 |

前端自动更新（可选）

import autoUpdate from 'build-version-json/client';

autoUpdate.start({
  allowedHosts: ['localhost', 'your-domain.com'],
});

监听 onmessageUpdate 事件展示更新提示：

window.addEventListener('onmessageUpdate', (event) => {
  console.log(event.detail.msg, event.detail.version);
});

构建产物

生产构建成功且开关开启时，输出目录会生成：

{
  "version": "1723872000123",
  "meta": "v1:..."
}

（无密钥时仅 { "version": "..." }）

API

const {
  BuildVersionWebpackPlugin,
  buildVersionVitePlugin,
  isBuildVersionNotifyEnabled,
  parseEnvFlag,
  defaultGenerateVersion,
  collectGitBuildMeta,
  encryptBuildMeta,
  decryptBuildMeta,
  resolveMetaSecret,
} = require('build-version-json');

子路径导出

| 路径 | 说明 | | ------ | ------ | | build-version-json | 主入口，导出全部 API | | build-version-json/webpack | 仅 Webpack 插件 | | build-version-json/vite | 仅 Vite 插件 | | build-version-json/client | 前端轮询模块（含 AutoUpdateOptions 类型） |

TypeScript 类型

主入口与子路径均提供 .d.ts 声明，常用导出：

| 类型 | 说明 | | ------ | ------ | | BuildVersionOptions | Webpack / Vite 插件配置 | | BuildVersionFormatPayload | formatContent 回调参数 | | AutoUpdateOptions | 前端 autoUpdate.start() 配置 | | OnMessageUpdateDetail | onmessageUpdate 事件 detail |

迁移说明

原包名 webpack-build-version 已弃用，请改用 build-version-json：

npm uninstall webpack-build-version
npm install --save-dev build-version-json

将 require('webpack-build-version') 替换为 require('build-version-json') 即可，API 保持不变。