vite-plugin-build-version-file 0.1.3 → 0.1.5

package/README.md

@@ -7,7 +7,16 @@
 - 构建产物中生成 `version.json`
 - 可选地向 HTML 注入 `window["__VERSION__"]`
 - 通过 `import.meta.env.__VERSION__` 在代码中直接读取版本号
-- 支持自定义版本号、文件名和全局变量名
+- 支持自定义版本号、文件名、全局变量名和额外数据
+
+这个插件只负责产出和暴露版本信息。
+
+它不负责这些运行时行为：
+
+- 轮询检查版本
+- 弹窗提示用户更新
+- 用户取消后的重试策略
+- 页面刷新时机
 
 适合用在这些场景：
 
@@ -53,6 +62,7 @@ export default defineConfig({
 - 开发态访问 `/version.json` 时返回版本信息
 - 构建后在输出目录生成 `version.json`
 - 构建后的 HTML 中注入 `window["__VERSION__"]`
+- 自动尝试读取业务项目 `package.json` 中的 `name` 和 `version`
 - 开发态默认版本号为 `0`
 - 构建态默认版本号为当前时间戳，格式为 `YYYYMMDDHHmmss`
 
@@ -60,8 +70,10 @@ export default defineConfig({
 
 ```json
 {
+  "pkgName": "your-app-name",
+  "pkgVersion": "1.0.0",
   "version": "20260401153045",
-  "production": true
+  "env": "production"
 }
 ```
 
@@ -69,11 +81,36 @@ export default defineConfig({
 
 ```json
 {
+  "pkgName": "your-app-name",
+  "pkgVersion": "1.0.0",
   "version": 0,
-  "production": false
+  "env": "development"
 }
 ```
 
+## 职责边界
+
+这个库的职责是：
+
+- 生成版本号
+- 输出 `version.json`
+- 向页面注入版本信息
+- 让业务代码能读取当前版本
+
+这些逻辑建议写在业务项目里，而不是放进这个库里：
+
+- 多久检查一次新版本
+- 请求失败后是否重试
+- 用什么 UI 提示用户
+- 用户点击取消后怎么处理
+- 是否立即刷新页面
+
+如果你的项目要做“检测到新版本后提示刷新”，推荐做法是：
+
+- 用 `import.meta.env.__VERSION__` 读取当前页面版本
+- 请求 `version.json` 读取服务端版本
+- 在业务项目里自行决定提示方式和刷新时机
+
 ## 配置项
 
 ```ts
@@ -87,6 +124,7 @@ type BuildVersionPluginOptions = {
   globalName?: string
   injectToHtml?: boolean
   version?: string | number | ((ctx: BuildVersionContext) => string | number)
+  data?: Record<string, any>
 }
 ```
 
@@ -112,10 +150,12 @@ type BuildVersionPluginOptions = {
 
 ```html
 <script>
-  window["__VERSION__"] = "20260401153045";
+  window["__VERSION__"] = { "version": "20260401153045", "env": "production" };
 </script>
 ```
 
+这里注入的是完整对象，不是单独的版本字符串。
+
 ### `injectToHtml`
 
 - 类型：`boolean`
@@ -142,6 +182,20 @@ type BuildVersionPluginOptions = {
 }
 ```
 
+### `data`
+
+- 类型：`Record<string, any>`
+- 默认值：`{}`
+- 作用：向最终生成的版本信息对象中追加自定义字段
+
+说明：
+
+- 插件会自动从业务项目的 `package.json` 中读取 `name` 和 `version`，分别写入 `pkgName` 和 `pkgVersion`
+- 查找位置是从当前 Vite 项目根目录开始，向上寻找最近的 `package.json`
+- 会同时影响开发态接口返回、构建产物中的 `version.json` 和注入到 `window` 的对象
+- 如果 `data` 里存在 `version` 或 `env` 同名字段，最终仍以插件生成的值为准
+- 如果 `data` 里存在 `pkgName` 或 `pkgVersion`，读取到业务项目 `package.json` 时会以自动读取的值为准；读取不到时会保留 `data` 里的值
+
 ## 使用示例
 
 ### 1. 使用默认配置
@@ -156,6 +210,11 @@ export default defineConfig({
 })
 ```
 
+默认情况下，插件会尝试从业务项目的 `package.json` 中读取：
+
+- `name` -> `pkgName`
+- `version` -> `pkgVersion`
+
 ### 2. 自定义全局变量名
 
 ```ts
@@ -176,7 +235,8 @@ export default defineConfig({
 注入后可以这样读取：
 
 ```ts
-const version = window['__APP_VERSION__']
+const payload = window['__APP_VERSION__']
+const version = payload.version
 ```
 
 ### 3. 只保留 `version.json`，不注入 `window`
@@ -242,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",
+  "version": "20260401153045",
+  "env": "production"
+}
+```
+
 ## 在项目中读取版本
 
 插件提供三种方式读取版本号，可根据场景选择：
@@ -276,10 +369,17 @@ interface ImportMeta {
 ### 方式二：读取注入的全局变量
 
 ```ts
-const version = window['__VERSION__']
+const payload = window['__VERSION__']
+
+console.log(payload.version)
+console.log(payload.env)
 ```
 
-**说明：** 需要确保 `injectToHtml` 为 `true`（默认值）
+**说明：**
+
+- 需要确保 `injectToHtml` 为 `true`（默认值）
+- 这里读到的是完整对象，不是单独字符串
+- 如果配置了 `data`，这里也可以直接读取对应字段
 
 ### 方式三：读取 `version.json`
 
@@ -288,11 +388,78 @@ const response = await fetch('/version.json')
 const payload = await response.json()
 
 console.log(payload.version)
-console.log(payload.production)
+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`
+
+async function checkVersion() {
+  try {
+    const response = await fetch(VERSION_URL, {
+      cache: 'no-store'
+    })
+
+    const payload = await response.json()
+
+    if (payload.version !== import.meta.env.__VERSION__) {
+      const shouldReload = await showUpdatePrompt()
+
+      if (shouldReload) {
+        window.location.reload()
+        return
+      }
+    }
+  } catch (error) {
+    console.warn('check version failed', error)
+  }
+
+  scheduleNextCheck()
+}
+
+function scheduleNextCheck() {
+  setTimeout(checkVersion, CHECK_INTERVAL)
+}
+
+function showUpdatePrompt() {
+  // 这里替换成你自己的弹窗、消息组件或确认框
+  return Promise.resolve(window.confirm('检测到新版本，是否刷新页面？'))
+}
+
+checkVersion()
+```
+
+建议：
+
+- 版本比较只判断 `payload.version` 和 `import.meta.env.__VERSION__` 是否一致
+- 提示方式由业务项目自己决定，可以是弹窗、消息条、通知或静默刷新
+- 轮询间隔不要过短，通常用 1 分钟或更长更合适
+- 请求失败后继续下一轮检查，避免一次失败后整个流程中断
+
+上面这段逻辑故意没有放进插件里，因为不同项目通常会有不同要求：
+
+- 轮询频率不同
+- 请求路径可能不同
+- 弹窗组件不同
+- 刷新策略不同
+- 失败重试策略不同
+
 ## 开发态行为说明
 
 开发态下，插件不会往项目的 `public/` 目录写文件。

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,8 +161,10 @@ function buildVersionPlugin(options = {}) {
         version = createDefaultVersion(context.command);
       }
       payload = {
+        ...data,
+        ...packageInfo,
         version,
-        production: config.command === "build"
+        env: config.mode
       };
       if (options.payload) {
         payload = options.payload(payload);

package/dist/index.d.cts

@@ -6,13 +6,15 @@ interface BuildVersionContext {
 }
 interface BuildVersionPayload {
     version: string | number;
-    production: boolean;
+    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

@@ -6,13 +6,15 @@ interface BuildVersionContext {
 }
 interface BuildVersionPayload {
     version: string | number;
-    production: boolean;
+    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,8 +136,10 @@ function buildVersionPlugin(options = {}) {
         version = createDefaultVersion(context.command);
       }
       payload = {
+        ...data,
+        ...packageInfo,
         version,
-        production: config.command === "build"
+        env: config.mode
       };
       if (options.payload) {
         payload = options.payload(payload);

package/package.json

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