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

package/README.md

@@ -1,4 +1,4 @@
-# vite-plugin-build-version
+# vite-plugin-build-version-file
 
 一个面向 `Vue 3 + Vite` 的构建版本插件。
 
@@ -6,6 +6,7 @@
 
 - 构建产物中生成 `version.json`
 - 可选地向 HTML 注入 `window["__VERSION__"]`
+- 通过 `import.meta.env.__VERSION__` 在代码中直接读取版本号
 - 支持自定义版本号、文件名和全局变量名
 
 适合用在这些场景：
@@ -24,13 +25,13 @@
 ## 安装
 
 ```bash
-pnpm add vite-plugin-build-version
+pnpm add vite-plugin-build-version-file
 ```
 
 也可以使用：
 
 ```bash
-npm install vite-plugin-build-version
+npm install vite-plugin-build-version-file
 ```
 
 ## 快速开始
@@ -38,7 +39,7 @@ npm install vite-plugin-build-version
 ```ts
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
-import buildVersionPlugin from 'vite-plugin-build-version'
+import buildVersionPlugin from 'vite-plugin-build-version-file'
 
 export default defineConfig({
   plugins: [vue(), buildVersionPlugin()]
@@ -148,7 +149,7 @@ type BuildVersionPluginOptions = {
 ```ts
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
-import buildVersionPlugin from 'vite-plugin-build-version'
+import buildVersionPlugin from 'vite-plugin-build-version-file'
 
 export default defineConfig({
   plugins: [vue(), buildVersionPlugin()]
@@ -160,7 +161,7 @@ export default defineConfig({
 ```ts
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
-import buildVersionPlugin from 'vite-plugin-build-version'
+import buildVersionPlugin from 'vite-plugin-build-version-file'
 
 export default defineConfig({
   plugins: [
@@ -183,7 +184,7 @@ const version = window['__APP_VERSION__']
 ```ts
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
-import buildVersionPlugin from 'vite-plugin-build-version'
+import buildVersionPlugin from 'vite-plugin-build-version-file'
 
 export default defineConfig({
   plugins: [
@@ -200,7 +201,7 @@ export default defineConfig({
 ```ts
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
-import buildVersionPlugin from 'vite-plugin-build-version'
+import buildVersionPlugin from 'vite-plugin-build-version-file'
 
 export default defineConfig({
   plugins: [
@@ -223,7 +224,7 @@ dist/meta/version.json
 ```ts
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
-import buildVersionPlugin from 'vite-plugin-build-version'
+import buildVersionPlugin from 'vite-plugin-build-version-file'
 
 export default defineConfig({
   plugins: [
@@ -243,13 +244,44 @@ export default defineConfig({
 
 ## 在项目中读取版本
 
-### 读取注入的全局变量
+插件提供三种方式读取版本号，可根据场景选择：
+
+### 方式一：通过 `import.meta.env` 读取（推荐）
+
+版本号会被注入到 `import.meta.env` 中，可以直接在代码中使用：
+
+```ts
+const version = import.meta.env.__VERSION__
+console.log(version) // '20260401153045' 或 '1.2.3'
+```
+
+**优势：**
+- 无需等待页面加载或发起请求
+- 类型安全，可在 `vite-env.d.ts` 中声明类型
+- 适合在应用初始化时读取版本
+
+**TypeScript 类型声明：**
+
+```ts
+// vite-env.d.ts
+interface ImportMetaEnv {
+  readonly __VERSION__: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}
+```
+
+### 方式二：读取注入的全局变量
 
 ```ts
 const version = window['__VERSION__']
 ```
 
-### 读取 `version.json`
+**说明：** 需要确保 `injectToHtml` 为 `true`（默认值）
+
+### 方式三：读取 `version.json`
 
 ```ts
 const response = await fetch('/version.json')

package/dist/index.cjs

@@ -24,10 +24,14 @@ __export(index_exports, {
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
-var PLUGIN_NAME = "vite-plugin-build-version";
+var PLUGIN_NAME = "vite-plugin-build-version-file";
 var DEFAULT_FILENAME = "version.json";
 var DEFAULT_GLOBAL_NAME = "__VERSION__";
-function formatBuildTimestamp(date) {
+function createDefaultVersion(command) {
+  if (command === "serve") {
+    return 0;
+  }
+  const date = /* @__PURE__ */ new Date();
   const pad = (value) => value.toString().padStart(2, "0");
   return [
     date.getFullYear(),
@@ -38,12 +42,6 @@ function formatBuildTimestamp(date) {
     pad(date.getSeconds())
   ].join("");
 }
-function createDefaultVersion(command) {
-  if (command === "serve") {
-    return 0;
-  }
-  return formatBuildTimestamp(/* @__PURE__ */ new Date());
-}
 function normalizeFileName(filename) {
   const normalized = filename.replace(/\\/g, "/").replace(/^\/+/, "");
   if (!normalized || normalized.endsWith("/")) {
@@ -57,28 +55,6 @@ function normalizeGlobalName(globalName) {
   }
   return globalName;
 }
-function ensureVersionValue(value) {
-  if (typeof value === "string" || typeof value === "number") {
-    return value;
-  }
-  throw new Error(
-    `[${PLUGIN_NAME}] "version" must resolve to a string or number.`
-  );
-}
-function resolveVersionValue(versionOption, context) {
-  if (versionOption === void 0) {
-    return createDefaultVersion(context.command);
-  }
-  if (typeof versionOption !== "function") {
-    return ensureVersionValue(versionOption);
-  }
-  try {
-    return ensureVersionValue(versionOption(context));
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`[${PLUGIN_NAME}] Failed to resolve version: ${message}`);
-  }
-}
 function serializePayload(payload) {
   return `${JSON.stringify(payload, null, 2)}
 `;
@@ -104,15 +80,45 @@ function buildVersionPlugin(options = {}) {
   let payload;
   return {
     name: PLUGIN_NAME,
+    config(config, { command }) {
+      const context = {
+        command,
+        mode: config.mode || "development"
+      };
+      let version;
+      if (typeof options.version === "function") {
+        version = options.version(context);
+      } else if (options.version !== void 0) {
+        version = options.version;
+      } else {
+        version = createDefaultVersion(context.command);
+      }
+      return {
+        define: {
+          [`import.meta.env.${globalName}`]: JSON.stringify(version)
+        }
+      };
+    },
     configResolved(config) {
       const context = {
         command: config.command,
         mode: config.mode
       };
+      let version;
+      if (typeof options.version === "function") {
+        version = options.version(context);
+      } else if (options.version !== void 0) {
+        version = options.version;
+      } else {
+        version = createDefaultVersion(context.command);
+      }
       payload = {
-        version: resolveVersionValue(options.version, context),
+        version,
         production: config.command === "build"
       };
+      if (options.payload) {
+        payload = options.payload(payload);
+      }
     },
     configureServer(server) {
       const requestPath = toRequestPath(server.config.base, fileName);
@@ -140,7 +146,7 @@ function buildVersionPlugin(options = {}) {
         {
           tag: "script",
           injectTo: "head",
-          children: `window[${JSON.stringify(globalName)}] = ${JSON.stringify(payload.version)};`
+          children: `window[${JSON.stringify(globalName)}] = ${JSON.stringify(payload)};`
         }
       ];
       return tags;
@@ -154,6 +160,12 @@ function buildVersionPlugin(options = {}) {
         fileName,
         source: serializePayload(payload)
       });
+      if (options.log) {
+        console.log(options.log(payload));
+      } else {
+        console.log("[vite-plugin-build-version-file][build finished]");
+        console.log(serializePayload(payload));
+      }
     }
   };
 }

package/dist/index.d.cts

@@ -13,6 +13,8 @@ interface BuildVersionPluginOptions {
     globalName?: string;
     injectToHtml?: boolean;
     version?: string | number | ((ctx: BuildVersionContext) => string | number);
+    log?: (content: any) => string;
+    payload?: (json: any) => any;
 }
 declare function buildVersionPlugin(options?: BuildVersionPluginOptions): Plugin;
 

package/dist/index.d.ts

@@ -13,6 +13,8 @@ interface BuildVersionPluginOptions {
     globalName?: string;
     injectToHtml?: boolean;
     version?: string | number | ((ctx: BuildVersionContext) => string | number);
+    log?: (content: any) => string;
+    payload?: (json: any) => any;
 }
 declare function buildVersionPlugin(options?: BuildVersionPluginOptions): Plugin;
 

package/dist/index.mjs

@@ -1,8 +1,12 @@
 // src/index.ts
-var PLUGIN_NAME = "vite-plugin-build-version";
+var PLUGIN_NAME = "vite-plugin-build-version-file";
 var DEFAULT_FILENAME = "version.json";
 var DEFAULT_GLOBAL_NAME = "__VERSION__";
-function formatBuildTimestamp(date) {
+function createDefaultVersion(command) {
+  if (command === "serve") {
+    return 0;
+  }
+  const date = /* @__PURE__ */ new Date();
   const pad = (value) => value.toString().padStart(2, "0");
   return [
     date.getFullYear(),
@@ -13,12 +17,6 @@ function formatBuildTimestamp(date) {
     pad(date.getSeconds())
   ].join("");
 }
-function createDefaultVersion(command) {
-  if (command === "serve") {
-    return 0;
-  }
-  return formatBuildTimestamp(/* @__PURE__ */ new Date());
-}
 function normalizeFileName(filename) {
   const normalized = filename.replace(/\\/g, "/").replace(/^\/+/, "");
   if (!normalized || normalized.endsWith("/")) {
@@ -32,28 +30,6 @@ function normalizeGlobalName(globalName) {
   }
   return globalName;
 }
-function ensureVersionValue(value) {
-  if (typeof value === "string" || typeof value === "number") {
-    return value;
-  }
-  throw new Error(
-    `[${PLUGIN_NAME}] "version" must resolve to a string or number.`
-  );
-}
-function resolveVersionValue(versionOption, context) {
-  if (versionOption === void 0) {
-    return createDefaultVersion(context.command);
-  }
-  if (typeof versionOption !== "function") {
-    return ensureVersionValue(versionOption);
-  }
-  try {
-    return ensureVersionValue(versionOption(context));
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`[${PLUGIN_NAME}] Failed to resolve version: ${message}`);
-  }
-}
 function serializePayload(payload) {
   return `${JSON.stringify(payload, null, 2)}
 `;
@@ -79,15 +55,45 @@ function buildVersionPlugin(options = {}) {
   let payload;
   return {
     name: PLUGIN_NAME,
+    config(config, { command }) {
+      const context = {
+        command,
+        mode: config.mode || "development"
+      };
+      let version;
+      if (typeof options.version === "function") {
+        version = options.version(context);
+      } else if (options.version !== void 0) {
+        version = options.version;
+      } else {
+        version = createDefaultVersion(context.command);
+      }
+      return {
+        define: {
+          [`import.meta.env.${globalName}`]: JSON.stringify(version)
+        }
+      };
+    },
     configResolved(config) {
       const context = {
         command: config.command,
         mode: config.mode
       };
+      let version;
+      if (typeof options.version === "function") {
+        version = options.version(context);
+      } else if (options.version !== void 0) {
+        version = options.version;
+      } else {
+        version = createDefaultVersion(context.command);
+      }
       payload = {
-        version: resolveVersionValue(options.version, context),
+        version,
         production: config.command === "build"
       };
+      if (options.payload) {
+        payload = options.payload(payload);
+      }
     },
     configureServer(server) {
       const requestPath = toRequestPath(server.config.base, fileName);
@@ -115,7 +121,7 @@ function buildVersionPlugin(options = {}) {
         {
           tag: "script",
           injectTo: "head",
-          children: `window[${JSON.stringify(globalName)}] = ${JSON.stringify(payload.version)};`
+          children: `window[${JSON.stringify(globalName)}] = ${JSON.stringify(payload)};`
         }
       ];
       return tags;
@@ -129,6 +135,12 @@ function buildVersionPlugin(options = {}) {
         fileName,
         source: serializePayload(payload)
       });
+      if (options.log) {
+        console.log(options.log(payload));
+      } else {
+        console.log("[vite-plugin-build-version-file][build finished]");
+        console.log(serializePayload(payload));
+      }
     }
   };
 }

package/package.json

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