@fengxingxingyun/automaticversion

一个同时兼容 Webpack 与 Vite 的「自动版本写入」插件。打包完成后自动在产物目录生成 version.json，并把 verifyVersion.js 复制到产物目录，用于前端发版后的自动刷新校验。

• 纯 ESM / 纯 CJS 双入口：package.json 已通过 exports 区分 import/require。在 Vite 的 ESM 配置中会被解析为 set-version.js（ESM），在 Webpack 的 CJS 配置中会被解析为 set-version.cjs（CJS），彻底避免 Dynamic require of "file:///.../set-version.js" is not supported 的报错。

• Vite 的 vite.config.js 既可以用 require(...) 也可以用 import ... from ...，插件均能正确加载。

• 框架无关：Vue 2/3、React 16+ 等主流框架均可使用（插件工作在打包器层面）。

• 自动确定写入路径：无需手动指定 dist，插件从打包器配置中解析。

• 兼容范围：webpack >=3 <6、vite >=2 <7（见 package.json 的 peerDependencies）。

安装

npm install @fengxingxingyun/automaticversion --save-dev
# 或
yarn add -D @fengxingxingyun/automaticversion

工作原理

1. 打包完成后（Webpack afterEmit / Vite closeBundle）自动执行。
2. 在产物目录写入 version.json，内容包含：

{
  "version": "<gitHash>-<timestamp>",
  "buildTime": "2026-08-21T14:44:50.907Z",
  "gitHash": "<gitHash>",
  "timestamp": 1787323490907
}

3. 把 verifyVersion.js 复制到产物目录，并自动注入到所有产物 HTML 入口（<head> 内），前端无需手动放置引用脚本，打包即可生效。

Vite 使用用例

基础用法（自动探测）

// vite.config.js
const { defineConfig } = require('vite');
const AutomaticVersion = require('@fengxingxingyun/automaticversion');

module.exports = defineConfig({
  build: {
    outDir: 'dist',
  },
  plugins: [
    AutomaticVersion(),
  ],
});

显式指定 Vite（推荐，避免误判）

// vite.config.js
const AutomaticVersion = require('@fengxingxingyun/automaticversion');

export default {
  build: {
    outDir: 'dist',
  },
  plugins: [
    AutomaticVersion.vite({
      fileName: 'version.json',
      verifyFileName: 'verifyVersion.js',
    }),
  ],
};

自定义版本号

// vite.config.js
const AutomaticVersion = require('@fengxingxingyun/automaticversion');

export default {
  plugins: [
    AutomaticVersion.vite({
      version: () => {
        const pkg = require('./package.json');
        return `${pkg.version}-${Date.now()}`;
      },
    }),
  ],
};

Webpack 使用用例

基础用法（自动探测）

// webpack.config.js
const AutomaticVersion = require('@fengxingxingyun/automaticversion');

module.exports = {
  output: {
    path: __dirname + '/dist',
  },
  plugins: [
    AutomaticVersion(),
  ],
};

显式指定 Webpack（推荐）

// webpack.config.js
const AutomaticVersion = require('@fengxingxingyun/automaticversion');

module.exports = {
  output: {
    path: __dirname + '/dist',
  },
  plugins: [
    AutomaticVersion.webpack({
      clean: true,
    }),
  ],
};

强制指定输出目录

// webpack.config.js
const path = require('path');
const AutomaticVersion = require('@fengxingxingyun/automaticversion');

module.exports = {
  output: { path: path.resolve(__dirname, 'build') },
  plugins: [
    AutomaticVersion.webpack({
      outputDir: path.resolve(__dirname, 'build'),
    }),
  ],
};

前端接入（自动注入，无需手动放置）

插件会在打包后自动把 <script src="./verifyVersion.js"></script> 注入到所有产物 HTML 入口（默认 <head> 内）。你什么都不用做，开箱即用：

• verifyVersion.js 与 version.json 一起被复制到产物目录；
• 所有 *.html（如 index.html）自动带上校验脚本引用；
• 已含引用的 HTML 不会被重复注入（幂等）。

自定义校验行为：在插件启用处传入 verifyConfig，插件会自动把配置脚本注入 HTML（位于校验脚本之前）。不传则校验脚本使用自身默认值，无需任何额外配置。

// vite.config.js / webpack.config.js
AutomaticVersion({
  verifyConfig: {
    url: './version.json',      // version 接口地址，默认 ./version.json
    storageKey: 'APP_VERSION',  // localStorage key，默认 RAINBOW_SEA_VERSION
    reload: true,               // 发现新版本是否自动刷新，默认 true
    interval: 60000,            // 轮询间隔(ms)，0 表示仅检查一次，默认 0
  },
});

关闭自动注入（改为手动引入）

如不想让插件改动 HTML，可关闭 injectVerify，再自行引入：

// vite.config.js / webpack.config.js
AutomaticVersion({
  injectVerify: false,
});

<!-- 手动放置：放在 head 顶部，优先于业务脚本执行 -->
<script src="/verifyVersion.js"></script>

或在 Vue / React 入口中：

// Vue 3 main.js
import { createApp } from 'vue';
import App from './App.vue';
import './verifyVersion.js';
createApp(App).mount('#app');

// React index.jsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import './verifyVersion.js';
ReactDOM.createRoot(document.getElementById('root')).render(<App />);

配置项

| 选项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | type | 'auto' \| 'webpack' \| 'vite' | 'auto' | 强制指定打包器类型，建议显式指定 | | fileName | string | 'version.json' | 版本信息文件名 | | verifyFileName | string | 'verifyVersion.js' | 拷贝到产物目录的校验脚本名 | | verifySource | string | 插件目录 | 校验脚本来源目录 | | outputDir | string | 打包器输出目录 | 强制指定产物目录（绝对路径） | | version | string \| function | gitHash-timestamp | 自定义版本号 | | clean | boolean | false | 写入前是否清理旧的 version 文件与校验脚本 | | space | number | 2 | version.json 缩进 | | silent | boolean | false | 是否关闭日志输出 | | injectVerify | boolean | true | 是否自动把校验脚本注入产物 HTML 入口 | | injectPosition | 'head' \| 'body' | 'head' | 注入位置，无匹配标签时追加到文件末尾 | | verifyConfig | object | undefined | 自定义校验参数，插件自动注入配置脚本；不传则用脚本默认值 |

兼容性说明

package.json 中已通过 peerDependencies 限定：

{
  "peerDependencies": {
    "webpack": ">=3.0.0 <6.0.0",
    "vite": ">=2.0.0 <7.0.0"
  }
}

两者均为可选依赖，按需安装其一即可。