vite-plugin-build-version-file 0.1.11 → 0.1.13

package/README.md

@@ -7,6 +7,7 @@
 - 开发态通过 dev server 提供 `version.json`
 - 构建后在输出目录生成 `version.json`
 - 普通 Vite HTML 自动注入 `window["__VERSION__"]`
+- 可选通过 `define` 将同一份 payload 编译进 JS 产物
 - VitePress 可通过顶层 `transformHtml` 注入同一份版本信息
 - 支持自定义版本号、输出文件名、全局变量名、时区和额外字段
 
@@ -127,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)
@@ -180,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`
@@ -350,6 +382,30 @@ checkVersion()
 - 弹窗、通知、静默刷新等策略放在业务项目里
 - 请求失败后继续下一轮检查，避免一次失败中断流程
 
+## 刷新指定项目缓存
+
+```ts
+import { clearUrlCache } from 'vite-plugin-build-version-file/client'
+
+await clearUrlCache('/vue-app/')
+```
+
+`url` 可省略；省略时默认使用当前 Vue 项目页面 URL：
+
+```ts
+await clearUrlCache()
+```
+
+Vue hash 路由会原样保留，缓存时间戳写在 `#` 前，确保服务器能够收到：
+
+```text
+https://cus.smarex.com.cn/pc/?_=随机值#/login?redirect=/dashboard/analysis
+```
+
+该方法仅支持同源 URL。它会绕过缓存请求 URL、强制刷新原 URL、通过隐藏 iframe 再次加载页面，最后携带随机时间戳跳转到该 URL。创建 iframe 前会销毁同一页面中已有的缓存刷新 iframe。单次请求或 iframe 加载失败不会阻断最终跳转。
+
+受浏览器限制，前端代码无法直接删除指定 URL 下的全部 HTTP 缓存；该方法只能尽可能刷新对应 Vue 项目的缓存。
+
 ## 开发态行为
 
 开发态下，插件不会向业务项目目录写入文件。
@@ -792,6 +848,30 @@ Recommendations:
 - Keep prompts, notifications, silent reloads, and retry rules in application code.
 - Continue polling after failed requests.
 
+## Refreshing a Project Cache
+
+```ts
+import { clearUrlCache } from 'vite-plugin-build-version-file/client'
+
+await clearUrlCache('/vue-app/')
+```
+
+The `url` argument is optional. When omitted, the current Vue project page URL is used:
+
+```ts
+await clearUrlCache()
+```
+
+Vue hash routes are preserved. The cache-busting timestamp is added before `#` so the server receives it:
+
+```text
+https://cus.smarex.com.cn/pc/?_=random-value#/login?redirect=/dashboard/analysis
+```
+
+This method only supports same-origin URLs. It bypasses the cached URL, forces a refresh of the original URL, loads the page again in a hidden iframe, and finally navigates to the URL with a random timestamp. Any existing cache-refresh iframe created by this method is removed before a new one is created. A failed request or iframe load does not prevent the final navigation.
+
+Browser code cannot directly delete every HTTP cache entry under a specific URL. This method refreshes the corresponding Vue application cache on a best-effort basis.
+
 ## Development Behavior
 
 In development, the plugin does not write files into your project directory.

package/dist/client.cjs

@@ -0,0 +1,81 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client.ts
+var client_exports = {};
+__export(client_exports, {
+  clearUrlCache: () => clearUrlCache
+});
+module.exports = __toCommonJS(client_exports);
+var CACHE_BUST_PARAM = "_";
+var IFRAME_ID = "vite-plugin-build-version-file-cache-iframe";
+var IFRAME_TIMEOUT = 5e3;
+function createCacheBustedUrl(url) {
+  const targetUrl = new URL(url, window.location.href);
+  const hash = targetUrl.hash;
+  targetUrl.hash = "";
+  targetUrl.searchParams.set(
+    CACHE_BUST_PARAM,
+    `${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+  targetUrl.hash = hash;
+  return targetUrl.href;
+}
+function loadIframe(url) {
+  return new Promise((resolve) => {
+    document.getElementById(IFRAME_ID)?.remove();
+    const iframe = document.createElement("iframe");
+    let completed = false;
+    const complete = () => {
+      if (completed) {
+        return;
+      }
+      completed = true;
+      window.clearTimeout(timeout);
+      resolve();
+    };
+    const timeout = window.setTimeout(complete, IFRAME_TIMEOUT);
+    iframe.hidden = true;
+    iframe.id = IFRAME_ID;
+    iframe.addEventListener("load", complete, { once: true });
+    iframe.addEventListener("error", complete, { once: true });
+    iframe.src = url;
+    document.documentElement.appendChild(iframe);
+  });
+}
+async function clearUrlCache(url = window.location.href) {
+  const targetUrl = new URL(url, window.location.href).href;
+  await Promise.allSettled([
+    fetch(createCacheBustedUrl(targetUrl), { cache: "no-store" }).then(
+      (response) => response.arrayBuffer()
+    ),
+    fetch(targetUrl, { cache: "reload" }).then(
+      (response) => response.arrayBuffer()
+    )
+  ]);
+  try {
+    await loadIframe(createCacheBustedUrl(targetUrl));
+  } finally {
+    window.location.replace(createCacheBustedUrl(targetUrl));
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearUrlCache
+});

package/dist/client.d.cts

@@ -0,0 +1,3 @@
+declare function clearUrlCache(url?: string): Promise<void>;
+
+export { clearUrlCache };

package/dist/client.d.ts

@@ -0,0 +1,3 @@
+declare function clearUrlCache(url?: string): Promise<void>;
+
+export { clearUrlCache };

package/dist/client.mjs

@@ -0,0 +1,56 @@
+// src/client.ts
+var CACHE_BUST_PARAM = "_";
+var IFRAME_ID = "vite-plugin-build-version-file-cache-iframe";
+var IFRAME_TIMEOUT = 5e3;
+function createCacheBustedUrl(url) {
+  const targetUrl = new URL(url, window.location.href);
+  const hash = targetUrl.hash;
+  targetUrl.hash = "";
+  targetUrl.searchParams.set(
+    CACHE_BUST_PARAM,
+    `${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+  targetUrl.hash = hash;
+  return targetUrl.href;
+}
+function loadIframe(url) {
+  return new Promise((resolve) => {
+    document.getElementById(IFRAME_ID)?.remove();
+    const iframe = document.createElement("iframe");
+    let completed = false;
+    const complete = () => {
+      if (completed) {
+        return;
+      }
+      completed = true;
+      window.clearTimeout(timeout);
+      resolve();
+    };
+    const timeout = window.setTimeout(complete, IFRAME_TIMEOUT);
+    iframe.hidden = true;
+    iframe.id = IFRAME_ID;
+    iframe.addEventListener("load", complete, { once: true });
+    iframe.addEventListener("error", complete, { once: true });
+    iframe.src = url;
+    document.documentElement.appendChild(iframe);
+  });
+}
+async function clearUrlCache(url = window.location.href) {
+  const targetUrl = new URL(url, window.location.href).href;
+  await Promise.allSettled([
+    fetch(createCacheBustedUrl(targetUrl), { cache: "no-store" }).then(
+      (response) => response.arrayBuffer()
+    ),
+    fetch(targetUrl, { cache: "reload" }).then(
+      (response) => response.arrayBuffer()
+    )
+  ]);
+  try {
+    await loadIframe(createCacheBustedUrl(targetUrl));
+  } finally {
+    window.location.replace(createCacheBustedUrl(targetUrl));
+  }
+}
+export {
+  clearUrlCache
+};

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,6 +193,9 @@ 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);
@@ -193,6 +209,24 @@ 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) {

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,6 +168,9 @@ 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);
@@ -168,6 +184,24 @@ 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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-build-version-file",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "A Vite plugin that emits version.json and injects version metadata into HTML.",
   "license": "MIT",
   "type": "module",
@@ -13,6 +13,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.mjs",
+      "require": "./dist/client.cjs"
     }
   },
   "files": [