vite-plugin-build-version-file 0.1.4 → 0.1.6

package/README.md

@@ -7,7 +7,7 @@
 - 构建产物中生成 `version.json`
 - 可选地向 HTML 注入 `window["__VERSION__"]`
 - 通过 `import.meta.env.__VERSION__` 在代码中直接读取版本号
-- 支持自定义版本号、文件名和全局变量名
+- 支持自定义版本号、文件名、全局变量名和额外数据
 
 这个插件只负责产出和暴露版本信息。
 
@@ -62,6 +62,7 @@ export default defineConfig({
 - 开发态访问 `/version.json` 时返回版本信息
 - 构建后在输出目录生成 `version.json`
 - 构建后的 HTML 中注入 `window["__VERSION__"]`
+- 自动尝试读取业务项目 `package.json` 中的 `name` 和 `version`
 - 开发态默认版本号为 `0`
 - 构建态默认版本号为当前时间戳，格式为 `YYYYMMDDHHmmss`
 
@@ -69,7 +70,9 @@ export default defineConfig({
 
 ```json
 {
-  "version": "20260401153045",
+  "pkgName": "your-app-name",
+  "pkgVersion": "1.0.0",
+  "time": "20260401153045",
   "env": "production"
 }
 ```
@@ -78,7 +81,9 @@ export default defineConfig({
 
 ```json
 {
-  "version": 0,
+  "pkgName": "your-app-name",
+  "pkgVersion": "1.0.0",
+  "time": 0,
   "env": "development"
 }
 ```
@@ -119,6 +124,7 @@ type BuildVersionPluginOptions = {
   globalName?: string
   injectToHtml?: boolean
   version?: string | number | ((ctx: BuildVersionContext) => string | number)
+  data?: Record<string, any>
 }
 ```
 
@@ -144,7 +150,7 @@ type BuildVersionPluginOptions = {
 
 ```html
 <script>
-  window["__VERSION__"] = { "version": "20260401153045", "env": "production" };
+  window["__VERSION__"] = { "time": "20260401153045", "env": "production" };
 </script>
 ```
 
@@ -176,6 +182,20 @@ type BuildVersionPluginOptions = {
 }
 ```
 
+### `data`
+
+- 类型：`Record<string, any>`
+- 默认值：`{}`
+- 作用：向最终生成的版本信息对象中追加自定义字段
+
+说明：
+
+- 插件会自动从业务项目的 `package.json` 中读取 `name` 和 `version`，分别写入 `pkgName` 和 `pkgVersion`
+- 查找位置是从当前 Vite 项目根目录开始，向上寻找最近的 `package.json`
+- 会同时影响开发态接口返回、构建产物中的 `version.json` 和注入到 `window` 的对象
+- 如果 `data` 里存在 `time` 或 `env` 同名字段，最终仍以插件生成的值为准
+- 如果 `data` 里存在 `pkgName` 或 `pkgVersion`，读取到业务项目 `package.json` 时会以自动读取的值为准；读取不到时会保留 `data` 里的值
+
 ## 使用示例
 
 ### 1. 使用默认配置
@@ -190,6 +210,11 @@ export default defineConfig({
 })
 ```
 
+默认情况下，插件会尝试从业务项目的 `package.json` 中读取：
+
+- `name` -> `pkgName`
+- `version` -> `pkgVersion`
+
 ### 2. 自定义全局变量名
 
 ```ts
@@ -211,7 +236,7 @@ export default defineConfig({
 
 ```ts
 const payload = window['__APP_VERSION__']
-const version = payload.version
+const time = payload.time
 ```
 
 ### 3. 只保留 `version.json`，不注入 `window`
@@ -277,6 +302,39 @@ export default defineConfig({
 })
 ```
 
+### 6. 追加自定义数据
+
+```ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import buildVersionPlugin from 'vite-plugin-build-version-file'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    buildVersionPlugin({
+      data: {
+        appName: 'admin',
+        gitBranch: 'release/2026-04',
+        commitSha: 'abc1234'
+      }
+    })
+  ]
+})
+```
+
+生成结果示例：
+
+```json
+{
+  "appName": "admin",
+  "gitBranch": "release/2026-04",
+  "commitSha": "abc1234",
+  "time": "20260401153045",
+  "env": "production"
+}
+```
+
 ## 在项目中读取版本
 
 插件提供三种方式读取版本号，可根据场景选择：
@@ -313,7 +371,7 @@ interface ImportMeta {
 ```ts
 const payload = window['__VERSION__']
 
-console.log(payload.version)
+console.log(payload.time)
 console.log(payload.env)
 ```
 
@@ -321,6 +379,7 @@ console.log(payload.env)
 
 - 需要确保 `injectToHtml` 为 `true`（默认值）
 - 这里读到的是完整对象，不是单独字符串
+- 如果配置了 `data`，这里也可以直接读取对应字段
 
 ### 方式三：读取 `version.json`
 
@@ -328,38 +387,71 @@ console.log(payload.env)
 const response = await fetch('/version.json')
 const payload = await response.json()
 
-console.log(payload.version)
+console.log(payload.time)
 console.log(payload.env)
 ```
 
 如果你配置了自定义 `filename`，这里的请求路径也需要改成对应地址。
 
+如果你配置了 `data`，返回结果中也会包含这些额外字段。
+
+默认情况下，如果业务项目存在 `package.json`，返回结果中也会包含：
+
+- `pkgName`
+- `pkgVersion`
+
 ## 在项目中做版本检查
 
 推荐把“检查新版本并提示刷新”的逻辑写在业务项目里。
 
-示例：
+通用伪代码：
+
+```js
+const CHECK_INTERVAL = 60 * 1000
+const VERSION_URL = `${import.meta.env.VITE_BASE_PATH}/version.json`
 
-```ts
 async function checkVersion() {
-  const response = await fetch(import.meta.env.VITE_BASE_PATH + '/version.json')
-  const payload = await response.json()
+  try {
+    const response = await fetch(VERSION_URL, {
+      cache: 'no-store'
+    })
 
-  if (payload.version !== import.meta.env.__VERSION__) {
-    const shouldReload = window.confirm('检测到新版本，是否刷新页面？')
+    const payload = await response.json()
 
-    if (shouldReload) {
-      window.location.reload()
-      return
+    if (payload.time !== import.meta.env.__VERSION__) {
+      const shouldReload = await showUpdatePrompt()
+
+      if (shouldReload) {
+        window.location.reload()
+        return
+      }
     }
+  } catch (error) {
+    console.warn('check version failed', error)
   }
 
-  setTimeout(checkVersion, 1000)
+  scheduleNextCheck()
+}
+
+function scheduleNextCheck() {
+  setTimeout(checkVersion, CHECK_INTERVAL)
+}
+
+function showUpdatePrompt() {
+  // 这里替换成你自己的弹窗、消息组件或确认框
+  return Promise.resolve(window.confirm('检测到新版本，是否刷新页面？'))
 }
 
 checkVersion()
 ```
 
+建议：
+
+- 版本比较只判断 `payload.time` 和 `import.meta.env.__VERSION__` 是否一致
+- 提示方式由业务项目自己决定，可以是弹窗、消息条、通知或静默刷新
+- 轮询间隔不要过短，通常用 1 分钟或更长更合适
+- 请求失败后继续下一轮检查，避免一次失败后整个流程中断
+
 上面这段逻辑故意没有放进插件里，因为不同项目通常会有不同要求：
 
 - 轮询频率不同

package/dist/index.cjs

@@ -24,6 +24,8 @@ __export(index_exports, {
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
+var import_node_fs = require("fs");
+var import_node_path = require("path");
 var PLUGIN_NAME = "vite-plugin-build-version-file";
 var DEFAULT_FILENAME = "version.json";
 var DEFAULT_GLOBAL_NAME = "__VERSION__";
@@ -55,6 +57,49 @@ function normalizeGlobalName(globalName) {
   }
   return globalName;
 }
+function normalizeData(data) {
+  if (data === void 0) {
+    return {};
+  }
+  if (!data || Array.isArray(data) || typeof data !== "object") {
+    throw new Error(`[${PLUGIN_NAME}] "data" must be a plain object.`);
+  }
+  return data;
+}
+function findNearestPackageJson(root) {
+  let currentDir = root;
+  while (true) {
+    const packageJsonPath = (0, import_node_path.join)(currentDir, "package.json");
+    if ((0, import_node_fs.existsSync)(packageJsonPath)) {
+      return packageJsonPath;
+    }
+    const parentDir = (0, import_node_path.dirname)(currentDir);
+    if (parentDir === currentDir) {
+      return void 0;
+    }
+    currentDir = parentDir;
+  }
+}
+function readPackageInfo(root) {
+  const packageJsonPath = findNearestPackageJson(root);
+  if (!packageJsonPath) {
+    return {};
+  }
+  try {
+    const content = (0, import_node_fs.readFileSync)(packageJsonPath, "utf-8");
+    const packageJson = JSON.parse(content);
+    const packageInfo = {};
+    if (packageJson.name !== void 0) {
+      packageInfo.pkgName = packageJson.name;
+    }
+    if (packageJson.version !== void 0) {
+      packageInfo.pkgVersion = packageJson.version;
+    }
+    return packageInfo;
+  } catch {
+    return {};
+  }
+}
 function serializePayload(payload) {
   return `${JSON.stringify(payload, null, 2)}
 `;
@@ -77,6 +122,8 @@ function buildVersionPlugin(options = {}) {
     options.globalName ?? DEFAULT_GLOBAL_NAME
   );
   const injectToHtml = options.injectToHtml ?? true;
+  const data = normalizeData(options.data);
+  let packageInfo = {};
   let payload;
   return {
     name: PLUGIN_NAME,
@@ -100,6 +147,7 @@ function buildVersionPlugin(options = {}) {
       };
     },
     configResolved(config) {
+      packageInfo = readPackageInfo(config.root);
       const context = {
         command: config.command,
         mode: config.mode
@@ -113,7 +161,9 @@ function buildVersionPlugin(options = {}) {
         version = createDefaultVersion(context.command);
       }
       payload = {
-        version,
+        ...data,
+        ...packageInfo,
+        time: version,
         env: config.mode
       };
       if (options.payload) {

package/dist/index.d.cts

@@ -5,14 +5,16 @@ interface BuildVersionContext {
     mode: string;
 }
 interface BuildVersionPayload {
-    version: string | number;
+    time: string | number;
     env: string;
+    [key: string]: any;
 }
 interface BuildVersionPluginOptions {
     filename?: string;
     globalName?: string;
     injectToHtml?: boolean;
     version?: string | number | ((ctx: BuildVersionContext) => string | number);
+    data?: Record<string, any>;
     log?: (content: any) => string;
     payload?: (json: any) => any;
 }

package/dist/index.d.ts

@@ -5,14 +5,16 @@ interface BuildVersionContext {
     mode: string;
 }
 interface BuildVersionPayload {
-    version: string | number;
+    time: string | number;
     env: string;
+    [key: string]: any;
 }
 interface BuildVersionPluginOptions {
     filename?: string;
     globalName?: string;
     injectToHtml?: boolean;
     version?: string | number | ((ctx: BuildVersionContext) => string | number);
+    data?: Record<string, any>;
     log?: (content: any) => string;
     payload?: (json: any) => any;
 }

package/dist/index.mjs

@@ -1,4 +1,6 @@
 // src/index.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
 var PLUGIN_NAME = "vite-plugin-build-version-file";
 var DEFAULT_FILENAME = "version.json";
 var DEFAULT_GLOBAL_NAME = "__VERSION__";
@@ -30,6 +32,49 @@ function normalizeGlobalName(globalName) {
   }
   return globalName;
 }
+function normalizeData(data) {
+  if (data === void 0) {
+    return {};
+  }
+  if (!data || Array.isArray(data) || typeof data !== "object") {
+    throw new Error(`[${PLUGIN_NAME}] "data" must be a plain object.`);
+  }
+  return data;
+}
+function findNearestPackageJson(root) {
+  let currentDir = root;
+  while (true) {
+    const packageJsonPath = join(currentDir, "package.json");
+    if (existsSync(packageJsonPath)) {
+      return packageJsonPath;
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      return void 0;
+    }
+    currentDir = parentDir;
+  }
+}
+function readPackageInfo(root) {
+  const packageJsonPath = findNearestPackageJson(root);
+  if (!packageJsonPath) {
+    return {};
+  }
+  try {
+    const content = readFileSync(packageJsonPath, "utf-8");
+    const packageJson = JSON.parse(content);
+    const packageInfo = {};
+    if (packageJson.name !== void 0) {
+      packageInfo.pkgName = packageJson.name;
+    }
+    if (packageJson.version !== void 0) {
+      packageInfo.pkgVersion = packageJson.version;
+    }
+    return packageInfo;
+  } catch {
+    return {};
+  }
+}
 function serializePayload(payload) {
   return `${JSON.stringify(payload, null, 2)}
 `;
@@ -52,6 +97,8 @@ function buildVersionPlugin(options = {}) {
     options.globalName ?? DEFAULT_GLOBAL_NAME
   );
   const injectToHtml = options.injectToHtml ?? true;
+  const data = normalizeData(options.data);
+  let packageInfo = {};
   let payload;
   return {
     name: PLUGIN_NAME,
@@ -75,6 +122,7 @@ function buildVersionPlugin(options = {}) {
       };
     },
     configResolved(config) {
+      packageInfo = readPackageInfo(config.root);
       const context = {
         command: config.command,
         mode: config.mode
@@ -88,7 +136,9 @@ function buildVersionPlugin(options = {}) {
         version = createDefaultVersion(context.command);
       }
       payload = {
-        version,
+        ...data,
+        ...packageInfo,
+        time: version,
         env: config.mode
       };
       if (options.payload) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-build-version-file",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "A Vite plugin that emits version.json and injects version metadata into HTML.",
   "license": "MIT",
   "type": "module",