vite-plugin-build-version-file 0.1.10 → 0.1.12

package/README.md

@@ -7,6 +7,7 @@
 - 开发态通过 dev server 提供 `version.json`
 - 构建后在输出目录生成 `version.json`
 - 普通 Vite HTML 自动注入 `window["__VERSION__"]`
+- 可选通过 `define` 将同一份 payload 编译进 JS 产物
 - VitePress 可通过顶层 `transformHtml` 注入同一份版本信息
 - 支持自定义版本号、输出文件名、全局变量名、时区和额外字段
 
@@ -78,6 +79,8 @@ export default defineConfig({
 
 注意：这里必须复用同一个 `buildVersion` 实例。不要分别调用两次 `buildVersionPlugin()`，否则 `transformHtml` 拿不到 Vite 插件阶段生成的 payload。
 
+VitePress 构建会包含 client bundle 和 SSR bundle。插件只在最终静态产物 bundle 输出 `version.json`，避免同一次 VitePress build 出现重复日志或重复 emit。
+
 ## 默认行为
 
 默认配置下，插件会做这些事：
@@ -125,6 +128,7 @@ type BuildVersionContext = {
 type BuildVersionPluginOptions = {
   filename?: string
   globalName?: string
+  defineName?: string | false
   injectToHtml?: boolean
   timeZone?: string
   version?: string | number | ((ctx: BuildVersionContext) => string | number)
@@ -178,6 +182,36 @@ dist/meta/version.json
 
 这里注入的是完整 payload 对象，不是单独版本字符串。
 
+### `defineName`
+
+- 类型：`string | false`
+- 默认值：`"__VERSION__"`
+- 作用：控制是否通过 Vite `define` 将完整 payload 编译进 JS 产物
+
+示例：
+
+```ts
+buildVersionPlugin({
+  defineName: '__APP_VERSION__'
+})
+```
+
+业务代码可直接读取：
+
+```ts
+console.log(__APP_VERSION__)
+```
+
+打包后会在编译阶段被替换成字面量对象，因此适合给 Vue、TS、JS 模块直接消费。
+
+默认情况下会注入 `__VERSION__`。如果你不需要编译期常量，可显式传 `defineName: false` 关闭。
+
+如果同时开启 `defineName` 和 `globalName`，两者会共用同一份 payload：
+
+- `defineName` 写入编译后的 JS
+- `globalName` 注入运行时 HTML
+- `version.json` 仍照常输出
+
 ### `injectToHtml`
 
 - 类型：`boolean`
@@ -387,6 +421,23 @@ pnpm build:fixture
 pnpm build:vitepress
 ```
 
+完整检查打包流程：
+
+```bash
+pnpm build
+pnpm build:fixture
+pnpm build:vitepress
+npm pack --dry-run
+```
+
+建议检查：
+
+- `debug/fixture-app/dist/version.json` 包含 `time`、`env`、`pkgName`、`pkgVersion`
+- `debug/fixture-app/dist/index.html` 只注入一次 `window["__VERSION__"]`
+- `debug/vitepress-app/.vitepress/dist/meta/version.json` 包含 `fixture`、`time`、`env`
+- VitePress 每个 HTML 只注入一次 `window["__VERSION__"]`
+- VitePress build 日志只输出一次插件 payload
+
 ## 发布
 
 ```bash
@@ -406,6 +457,7 @@ npm publish --access public
 - `version.json` 输出正常
 - 普通 Vite HTML 注入正常
 - VitePress `transformHtml` 接入后注入正常
+- VitePress build 没有重复输出插件 payload 日志
 
 查看最终发包内容：
 
@@ -502,6 +554,8 @@ export default defineConfig({
 
 Use the same `buildVersion` instance in both places. Calling `buildVersionPlugin()` twice creates two isolated instances, and the VitePress `transformHtml` helper will not receive the payload created during the Vite plugin lifecycle.
 
+VitePress build includes a client bundle and an SSR bundle. The plugin emits `version.json` only from the final static bundle, so one VitePress build does not print duplicate payload logs or emit the same asset twice.
+
 ## Default Behavior
 
 With default options, the plugin:
@@ -809,6 +863,23 @@ pnpm build:fixture
 pnpm build:vitepress
 ```
 
+Full local package check:
+
+```bash
+pnpm build
+pnpm build:fixture
+pnpm build:vitepress
+npm pack --dry-run
+```
+
+Check:
+
+- `debug/fixture-app/dist/version.json` contains `time`, `env`, `pkgName`, and `pkgVersion`
+- `debug/fixture-app/dist/index.html` injects `window["__VERSION__"]` once
+- `debug/vitepress-app/.vitepress/dist/meta/version.json` contains `fixture`, `time`, and `env`
+- each VitePress HTML file injects `window["__VERSION__"]` once
+- VitePress build prints the plugin payload log once
+
 ## Publishing
 
 ```bash
@@ -828,6 +899,7 @@ Before publishing, check:
 - `version.json` output
 - normal Vite HTML injection
 - VitePress `transformHtml` injection
+- no duplicate plugin payload logs during VitePress build
 
 Inspect the publish package:
 

package/dist/index.cjs

@@ -29,6 +29,7 @@ var import_node_path = require("path");
 var PLUGIN_NAME = "vite-plugin-build-version-file";
 var DEFAULT_FILENAME = "version.json";
 var DEFAULT_GLOBAL_NAME = "__VERSION__";
+var DEFAULT_DEFINE_NAME = "__VERSION__";
 var DEFAULT_TIME_ZONE = "Asia/Shanghai";
 function createDefaultVersion(command, timeZone) {
   if (command === "serve") {
@@ -70,6 +71,15 @@ function normalizeGlobalName(globalName) {
   }
   return globalName;
 }
+function normalizeDefineName(defineName) {
+  if (defineName === false || defineName === void 0) {
+    return defineName ?? false;
+  }
+  if (!defineName.trim()) {
+    throw new Error(`[${PLUGIN_NAME}] "defineName" cannot be empty.`);
+  }
+  return defineName;
+}
 function normalizeTimeZone(timeZone) {
   const normalized = timeZone.trim();
   if (!normalized) {
@@ -154,6 +164,9 @@ function toRequestPath(base, fileName) {
   const baseWithoutTrailingSlash = withLeadingSlash.endsWith("/") ? withLeadingSlash.slice(0, -1) : withLeadingSlash;
   return `${baseWithoutTrailingSlash}/${fileName}`.replace(/\/{2,}/g, "/");
 }
+function resolveProjectRoot(root) {
+  return root ? (0, import_node_path.resolve)(process.cwd(), root) : process.cwd();
+}
 function resolveVersion(options, context, timeZone) {
   if (typeof options.version === "function") {
     return options.version(context);
@@ -180,10 +193,14 @@ function buildVersionPlugin(options = {}) {
   const globalName = normalizeGlobalName(
     options.globalName ?? DEFAULT_GLOBAL_NAME
   );
+  const defineName = normalizeDefineName(
+    options.defineName ?? DEFAULT_DEFINE_NAME
+  );
   const injectToHtml = options.injectToHtml ?? true;
   const timeZone = normalizeTimeZone(options.timeZone ?? DEFAULT_TIME_ZONE);
   const data = normalizeData(options.data);
   let payload;
+  let skipBundleEmit = false;
   const transformHtml = (code, ..._args) => {
     if (!injectToHtml || !payload) {
       return void 0;
@@ -192,7 +209,26 @@ function buildVersionPlugin(options = {}) {
   };
   const plugin = {
     name: PLUGIN_NAME,
+    config(userConfig, env) {
+      if (!payload) {
+        const context = {
+          command: env.command,
+          mode: env.mode
+        };
+        const packageInfo = readPackageInfo(resolveProjectRoot(userConfig.root));
+        payload = createPayload(options, context, data, timeZone, packageInfo);
+      }
+      if (!defineName || !payload) {
+        return void 0;
+      }
+      return {
+        define: {
+          [defineName]: JSON.stringify(payload)
+        }
+      };
+    },
     configResolved(config) {
+      skipBundleEmit = Boolean(config.build.ssr) && !config.build.ssrEmitAssets;
       if (payload) {
         return;
       }
@@ -235,7 +271,7 @@ function buildVersionPlugin(options = {}) {
       return tags;
     },
     generateBundle() {
-      if (!payload) {
+      if (!payload || skipBundleEmit) {
         return;
       }
       this.emitFile({

package/dist/index.d.cts

@@ -12,6 +12,7 @@ interface BuildVersionPayload {
 interface BuildVersionPluginOptions {
     filename?: string;
     globalName?: string;
+    defineName?: string | false;
     injectToHtml?: boolean;
     timeZone?: string;
     version?: string | number | ((ctx: BuildVersionContext) => string | number);

package/dist/index.d.ts

@@ -12,6 +12,7 @@ interface BuildVersionPayload {
 interface BuildVersionPluginOptions {
     filename?: string;
     globalName?: string;
+    defineName?: string | false;
     injectToHtml?: boolean;
     timeZone?: string;
     version?: string | number | ((ctx: BuildVersionContext) => string | number);

package/dist/index.mjs

@@ -1,9 +1,10 @@
 // src/index.ts
 import { existsSync, readFileSync } from "fs";
-import { dirname, join } from "path";
+import { dirname, join, resolve } from "path";
 var PLUGIN_NAME = "vite-plugin-build-version-file";
 var DEFAULT_FILENAME = "version.json";
 var DEFAULT_GLOBAL_NAME = "__VERSION__";
+var DEFAULT_DEFINE_NAME = "__VERSION__";
 var DEFAULT_TIME_ZONE = "Asia/Shanghai";
 function createDefaultVersion(command, timeZone) {
   if (command === "serve") {
@@ -45,6 +46,15 @@ function normalizeGlobalName(globalName) {
   }
   return globalName;
 }
+function normalizeDefineName(defineName) {
+  if (defineName === false || defineName === void 0) {
+    return defineName ?? false;
+  }
+  if (!defineName.trim()) {
+    throw new Error(`[${PLUGIN_NAME}] "defineName" cannot be empty.`);
+  }
+  return defineName;
+}
 function normalizeTimeZone(timeZone) {
   const normalized = timeZone.trim();
   if (!normalized) {
@@ -129,6 +139,9 @@ function toRequestPath(base, fileName) {
   const baseWithoutTrailingSlash = withLeadingSlash.endsWith("/") ? withLeadingSlash.slice(0, -1) : withLeadingSlash;
   return `${baseWithoutTrailingSlash}/${fileName}`.replace(/\/{2,}/g, "/");
 }
+function resolveProjectRoot(root) {
+  return root ? resolve(process.cwd(), root) : process.cwd();
+}
 function resolveVersion(options, context, timeZone) {
   if (typeof options.version === "function") {
     return options.version(context);
@@ -155,10 +168,14 @@ function buildVersionPlugin(options = {}) {
   const globalName = normalizeGlobalName(
     options.globalName ?? DEFAULT_GLOBAL_NAME
   );
+  const defineName = normalizeDefineName(
+    options.defineName ?? DEFAULT_DEFINE_NAME
+  );
   const injectToHtml = options.injectToHtml ?? true;
   const timeZone = normalizeTimeZone(options.timeZone ?? DEFAULT_TIME_ZONE);
   const data = normalizeData(options.data);
   let payload;
+  let skipBundleEmit = false;
   const transformHtml = (code, ..._args) => {
     if (!injectToHtml || !payload) {
       return void 0;
@@ -167,7 +184,26 @@ function buildVersionPlugin(options = {}) {
   };
   const plugin = {
     name: PLUGIN_NAME,
+    config(userConfig, env) {
+      if (!payload) {
+        const context = {
+          command: env.command,
+          mode: env.mode
+        };
+        const packageInfo = readPackageInfo(resolveProjectRoot(userConfig.root));
+        payload = createPayload(options, context, data, timeZone, packageInfo);
+      }
+      if (!defineName || !payload) {
+        return void 0;
+      }
+      return {
+        define: {
+          [defineName]: JSON.stringify(payload)
+        }
+      };
+    },
     configResolved(config) {
+      skipBundleEmit = Boolean(config.build.ssr) && !config.build.ssrEmitAssets;
       if (payload) {
         return;
       }
@@ -210,7 +246,7 @@ function buildVersionPlugin(options = {}) {
       return tags;
     },
     generateBundle() {
-      if (!payload) {
+      if (!payload || skipBundleEmit) {
         return;
       }
       this.emitFile({

package/package.json

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