vite-plugin-build-version-file 0.1.16 → 0.1.18

package/README.md

@@ -27,6 +27,7 @@
 - Vite 项目
 - Vue 3 + Vite 项目
 - VitePress 项目
+- Nuxt 项目（需自行接 `render:html`，见下）
 - `peerDependencies` 要求 `vite >= 5`
 - Node.js 要求 `>= 18`
 
@@ -81,6 +82,33 @@ export default defineConfig({
 
 VitePress 构建会包含 client bundle 和 SSR bundle。插件只在最终静态产物 bundle 输出 `version.json`，避免同一次 VitePress build 出现重复日志或重复 emit。
 
+### Nuxt 项目
+
+Nuxt 的 HTML 由 Nitro 渲染，Vite 客户端构建的入口是 JS 模块而不是 `index.html`，所以插件的 `transformIndexHtml` 在 Nuxt 里不会被调用，`window["__VERSION__"]` 不会自动注入。
+
+同样复用同一个插件实例，把它的 `headScript()` 推进 Nuxt `render:html` 钩子的 `html.head` 数组：
+
+```ts
+import buildVersionPlugin from 'vite-plugin-build-version-file'
+
+const buildVersion = buildVersionPlugin()
+
+export default defineNuxtConfig({
+  vite: {
+    plugins: [buildVersion]
+  },
+  hooks: {
+    'render:html'(html) {
+      html.head.push(buildVersion.headScript())
+    }
+  }
+})
+```
+
+`headScript()` 返回完整的 `<script>...</script>` 片段；`injectToHtml: false` 时、或 payload 还没生成时返回空字符串（不抛错），所以直接 `push` 是安全的。
+
+注意 Nuxt 里 `version.json` 的落点和 Vite / VitePress 不同：插件通过 `generateBundle` emit 到 Vite 客户端构建目录的根，而 Nuxt 发布到静态目录的是 assetsDir 内的内容，根目录上的文件不会被带出去。需要线上能访问这个文件时，要么把 `filename` 指到 assetsDir 内（例如 `_nuxt/version.json`），要么在构建后自行复制到 public 目录。
+
 ## 默认行为
 
 默认配置下，插件会做这些事：
@@ -342,45 +370,97 @@ console.log(payload.env)
 
 ## 做版本检查
 
-插件不内置版本检查 UI。推荐业务项目自行处理：
+插件不内置版本检查 UI。推荐业务项目自行处理。下面示例可以直接放到应用入口、布局组件或独立的版本检查模块中：
 
 ```js
 const CHECK_INTERVAL = 60 * 1000
+const CANCEL_RETRY_DELAY = 5 * 60 * 1000
 const VERSION_URL = '/version.json'
 
+// 使用 window 共享状态，避免多个组件或入口各自创建轮询和更新弹窗。
+const versionCheckState = (window.__VERSION_CHECK_STATE__ ??= {
+  timer: 0,
+  checking: false,
+  promptPromise: null
+})
+
+function scheduleVersionCheck(delay) {
+  window.clearTimeout(versionCheckState.timer)
+  versionCheckState.timer = window.setTimeout(() => {
+    void checkVersion()
+  }, delay)
+}
+
+function showUpdatePrompt() {
+  if (versionCheckState.promptPromise) {
+    return versionCheckState.promptPromise
+  }
+
+  // 使用 Element Plus 等异步弹窗时，替换为返回 Promise<boolean> 的业务弹窗函数。
+  versionCheckState.promptPromise = Promise.resolve(
+    window.confirm('检测到新版本，是否立即刷新页面？')
+  ).finally(() => {
+    versionCheckState.promptPromise = null
+  })
+
+  return versionCheckState.promptPromise
+}
+
 async function checkVersion() {
+  // 防止多个入口同时发起版本请求。
+  if (versionCheckState.checking) {
+    return
+  }
+
+  versionCheckState.checking = true
+  let nextDelay = CHECK_INTERVAL
+
   try {
     const response = await fetch(VERSION_URL, {
       cache: 'no-store'
     })
+
+    if (!response.ok) {
+      throw new Error(`version request failed: ${response.status}`)
+    }
+
     const latestPayload = await response.json()
     const currentPayload = window.__VERSION__
 
     if (currentPayload && latestPayload.time !== currentPayload.time) {
-      const shouldReload = window.confirm('检测到新版本，是否刷新页面？')
+      const shouldReload = await showUpdatePrompt()
 
       if (shouldReload) {
         window.location.reload()
         return
       }
+
+      // 用户取消后，5 分钟后再检查，避免短时间内重复打扰。
+      nextDelay = CANCEL_RETRY_DELAY
     }
   } catch (error) {
     console.warn('check version failed', error)
+  } finally {
+    versionCheckState.checking = false
+    scheduleVersionCheck(nextDelay)
   }
-
-  window.setTimeout(checkVersion, CHECK_INTERVAL)
 }
 
-checkVersion()
+void checkVersion()
 ```
 
-建议：
+这个示例有几个关键点：
 
 - 通常比较 `payload.time` 即可
 - 请求 `version.json` 时使用 `cache: 'no-store'`
-- 轮询间隔不要过短，通常 1 分钟或更长
-- 弹窗、通知、静默刷新等策略放在业务项目里
-- 请求失败后继续下一轮检查，避免一次失败中断流程
+- `window.__VERSION_CHECK_STATE__` 是当前页面内的共享状态；多个组件重复调用 `checkVersion()` 时，只会保留一个检查流程
+- `promptPromise` 让更新弹窗成为单例；同一时间已有弹窗时，不会再次弹出
+- 用户确认后立即刷新页面；用户取消后固定等待 5 分钟，再开始下一次检查
+- 没有检测到更新或请求失败时，按 `CHECK_INTERVAL` 继续检查
+- `CHECK_INTERVAL` 通常设置为 1 分钟或更长，避免产生过多请求
+- 如果项目配置了自定义 `globalName`，将示例中的 `window.__VERSION__` 换成对应的全局变量
+
+示例使用原生 `window.confirm`，因此不依赖 UI 框架。接入 Element Plus、Ant Design 等异步弹窗时，只需让 `showUpdatePrompt` 内部调用业务弹窗，并在确认/取消时分别返回 `true`/`false`；不要在多个组件中各自维护一份弹窗状态。
 
 ## 刷新指定项目缓存
 
@@ -389,10 +469,13 @@ import { clearUrlCache } from 'vite-plugin-build-version-file/client'
 
 await clearUrlCache({
   urls: ['/vue-app/', '/vue-app/index.html'],
-  redirectUrl: '/vue-app/'
+  redirectUrl: '/vue-app/',
+  time: 5
 })
 ```
 
+调用后会显示全屏 loading 和刷新倒计时。`time` 单位为秒，默认值为 `5`；缓存处理提前完成时会立即刷新，到达时限后则无论调用结果如何都会刷新。
+
 参数对象可省略。无参时按顺序检测以下两组 URL：
 
 1. `location.origin + location.pathname`
@@ -534,6 +617,7 @@ Those behaviors should stay in your application code.
 - Vite projects
 - Vue 3 + Vite projects
 - VitePress projects
+- Nuxt projects (wire up `render:html` yourself, see below)
 - `vite >= 5`
 - Node.js `>= 18`
 
@@ -588,6 +672,33 @@ Use the same `buildVersion` instance in both places. Calling `buildVersionPlugin
 
 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.
 
+### Nuxt
+
+Nuxt renders HTML through Nitro, and its Vite client build entry is a JS module rather than an `index.html`, so the plugin's `transformIndexHtml` is never called and `window["__VERSION__"]` is not injected automatically.
+
+Reuse the same plugin instance and push its `headScript()` into the `html.head` array of the Nuxt `render:html` hook:
+
+```ts
+import buildVersionPlugin from 'vite-plugin-build-version-file'
+
+const buildVersion = buildVersionPlugin()
+
+export default defineNuxtConfig({
+  vite: {
+    plugins: [buildVersion]
+  },
+  hooks: {
+    'render:html'(html) {
+      html.head.push(buildVersion.headScript())
+    }
+  }
+})
+```
+
+`headScript()` returns a complete `<script>...</script>` snippet. It returns an empty string when `injectToHtml: false` or when the payload has not been created yet, so pushing it directly is safe.
+
+Note that `version.json` lands in a different place in Nuxt: the plugin emits it through `generateBundle` at the root of the Vite client build directory, while Nuxt publishes the contents of the assetsDir into the static output. Files sitting at that build root are not carried over. If the file must be reachable in production, either point `filename` inside the assetsDir (for example `_nuxt/version.json`) or copy it into the public directory after the build.
+
 ## Default Behavior
 
 With default options, the plugin:
@@ -816,45 +927,97 @@ Use this when you need to compare the current page against the latest deployed v
 
 ## Checking for Updates
 
-The plugin does not include update-checking UI. Keep that logic in your app.
+The plugin does not include update-checking UI. Keep that logic in your app. The following example can be placed in your app entry, layout component, or a dedicated version-check module:
 
 ```js
 const CHECK_INTERVAL = 60 * 1000
+const CANCEL_RETRY_DELAY = 5 * 60 * 1000
 const VERSION_URL = '/version.json'
 
+// 使用 window 共享状态，让多个组件或入口复用同一套检查和弹窗。
+const versionCheckState = (window.__VERSION_CHECK_STATE__ ??= {
+  timer: 0,
+  checking: false,
+  promptPromise: null
+})
+
+function scheduleVersionCheck(delay) {
+  window.clearTimeout(versionCheckState.timer)
+  versionCheckState.timer = window.setTimeout(() => {
+    void checkVersion()
+  }, delay)
+}
+
+function showUpdatePrompt() {
+  if (versionCheckState.promptPromise) {
+    return versionCheckState.promptPromise
+  }
+
+  // 使用异步业务弹窗时，替换为返回 Promise<boolean> 的弹窗函数。
+  versionCheckState.promptPromise = Promise.resolve(
+    window.confirm('A new version is available. Reload now?')
+  ).finally(() => {
+    versionCheckState.promptPromise = null
+  })
+
+  return versionCheckState.promptPromise
+}
+
 async function checkVersion() {
+  // 防止多个入口同时发起版本请求。
+  if (versionCheckState.checking) {
+    return
+  }
+
+  versionCheckState.checking = true
+  let nextDelay = CHECK_INTERVAL
+
   try {
     const response = await fetch(VERSION_URL, {
       cache: 'no-store'
     })
+
+    if (!response.ok) {
+      throw new Error(`version request failed: ${response.status}`)
+    }
+
     const latestPayload = await response.json()
     const currentPayload = window.__VERSION__
 
     if (currentPayload && latestPayload.time !== currentPayload.time) {
-      const shouldReload = window.confirm('A new version is available. Reload now?')
+      const shouldReload = await showUpdatePrompt()
 
       if (shouldReload) {
         window.location.reload()
         return
       }
+
+      // 用户取消后，等待 5 分钟再开始下一次检查。
+      nextDelay = CANCEL_RETRY_DELAY
     }
   } catch (error) {
     console.warn('check version failed', error)
+  } finally {
+    versionCheckState.checking = false
+    scheduleVersionCheck(nextDelay)
   }
-
-  window.setTimeout(checkVersion, CHECK_INTERVAL)
 }
 
-checkVersion()
+void checkVersion()
 ```
 
-Recommendations:
+Key points:
 
 - Compare `payload.time` in most cases.
 - Fetch `version.json` with `cache: 'no-store'`.
-- Avoid very short polling intervals. One minute or longer is usually enough.
-- Keep prompts, notifications, silent reloads, and retry rules in application code.
-- Continue polling after failed requests.
+- `window.__VERSION_CHECK_STATE__` is shared by the current page. Repeated `checkVersion()` calls reuse one check flow.
+- `promptPromise` makes the update prompt a singleton, so an already-open prompt is not shown again.
+- Confirming reloads immediately. Canceling waits five minutes before the next check.
+- No update or a failed request uses `CHECK_INTERVAL` for the next check.
+- Set `CHECK_INTERVAL` to one minute or longer to avoid excessive requests.
+- If you configure a custom `globalName`, replace `window.__VERSION__` with that global variable.
+
+The example uses native `window.confirm`, so it has no UI framework dependency. With Element Plus, Ant Design, or another async dialog, replace the body of `showUpdatePrompt` with your app dialog and resolve `true` on confirm or `false` on cancel. Keep the shared state in one global object instead of maintaining separate prompt state in each component.
 
 ## Refreshing a Project Cache
 
@@ -863,10 +1026,13 @@ import { clearUrlCache } from 'vite-plugin-build-version-file/client'
 
 await clearUrlCache({
   urls: ['/vue-app/', '/vue-app/index.html'],
-  redirectUrl: '/vue-app/'
+  redirectUrl: '/vue-app/',
+  time: 5
 })
 ```
 
+The method displays a full-screen loading mask and refresh countdown after it is called. `time` is measured in seconds and defaults to `5`. It refreshes immediately if cache processing finishes early; once the limit is reached, it refreshes regardless of the processing result.
+
 The options object is optional. Without arguments, the following URL groups are checked in order:
 
 1. `location.origin + location.pathname`

package/dist/client.cjs

@@ -25,7 +25,32 @@ __export(client_exports, {
 module.exports = __toCommonJS(client_exports);
 var CACHE_BUST_PARAM = "_";
 var IFRAME_ID = "vite-plugin-build-version-file-cache-iframe";
+var LOADING_ID = "vite-plugin-build-version-file-loading";
 var IFRAME_TIMEOUT = 5e3;
+var DEFAULT_REFRESH_TIME = 5;
+function showLoading(time) {
+  document.getElementById(LOADING_ID)?.remove();
+  const loading = document.createElement("div");
+  const spinner = document.createElement("div");
+  const text = document.createElement("div");
+  const deadline = Date.now() + time * 1e3;
+  loading.id = LOADING_ID;
+  loading.style.cssText = "position:fixed;inset:0;z-index:2147483647;display:flex;flex-direction:column;align-items:center;justify-content:center;background:rgba(0,0,0,.65);color:#fff;font:14px/1.5 sans-serif;";
+  spinner.style.cssText = "width:36px;height:36px;margin-bottom:16px;border:3px solid rgba(255,255,255,.35);border-top-color:#fff;border-radius:50%;animation:vite-build-version-loading .8s linear infinite;";
+  text.textContent = `\u8BF7\u7A0D\u7B49\uFF0C\u6B63\u5728\u68C0\u6D4B\u66F4\u65B0...\uFF08${Math.ceil(time)}\u79D2\uFF09`;
+  const style = document.createElement("style");
+  style.textContent = "@keyframes vite-build-version-loading{to{transform:rotate(360deg)}}";
+  loading.append(style, spinner, text);
+  document.documentElement.appendChild(loading);
+  const countdown = window.setInterval(() => {
+    const seconds = Math.max(0, Math.ceil((deadline - Date.now()) / 1e3));
+    text.textContent = `\u8BF7\u7A0D\u7B49\uFF0C\u6B63\u5728\u68C0\u6D4B\u66F4\u65B0...\uFF08${seconds}\u79D2\uFF09`;
+  }, 1e3);
+  return () => {
+    window.clearInterval(countdown);
+    loading.remove();
+  };
+}
 function createCacheBustedUrl(url) {
   const targetUrl = new URL(url, window.location.href);
   const hash = targetUrl.hash;
@@ -83,18 +108,31 @@ async function clearTargetUrlCache(url) {
 async function clearUrlCache(options = {}) {
   const defaultUrl = window.location.origin + window.location.pathname;
   const urls = options.urls ?? [defaultUrl, createIndexUrl(defaultUrl)];
+  const configuredTime = options.time;
+  const time = typeof configuredTime === "number" && Number.isFinite(configuredTime) && configuredTime > 0 ? configuredTime : DEFAULT_REFRESH_TIME;
   const redirectUrl = new URL(
     options.redirectUrl ?? urls[0] ?? defaultUrl,
     window.location.href
   ).href;
+  const hideLoading = showLoading(time);
+  let refreshTimeout = 0;
   try {
-    for (const url of urls) {
-      try {
-        await clearTargetUrlCache(url);
-      } catch {
-      }
-    }
+    await Promise.race([
+      (async () => {
+        for (const url of urls) {
+          try {
+            await clearTargetUrlCache(url);
+          } catch {
+          }
+        }
+      })(),
+      new Promise((resolve) => {
+        refreshTimeout = window.setTimeout(resolve, time * 1e3);
+      })
+    ]);
   } finally {
+    window.clearTimeout(refreshTimeout);
+    hideLoading();
     window.location.replace(createCacheBustedUrl(redirectUrl));
   }
 }

package/dist/client.d.cts

@@ -1,6 +1,7 @@
 interface ClearUrlCacheOptions {
     urls?: string[];
     redirectUrl?: string;
+    time?: number;
 }
 declare function clearUrlCache(options?: ClearUrlCacheOptions): Promise<void>;
 

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 interface ClearUrlCacheOptions {
     urls?: string[];
     redirectUrl?: string;
+    time?: number;
 }
 declare function clearUrlCache(options?: ClearUrlCacheOptions): Promise<void>;
 

package/dist/client.mjs

@@ -1,7 +1,32 @@
 // src/client.ts
 var CACHE_BUST_PARAM = "_";
 var IFRAME_ID = "vite-plugin-build-version-file-cache-iframe";
+var LOADING_ID = "vite-plugin-build-version-file-loading";
 var IFRAME_TIMEOUT = 5e3;
+var DEFAULT_REFRESH_TIME = 5;
+function showLoading(time) {
+  document.getElementById(LOADING_ID)?.remove();
+  const loading = document.createElement("div");
+  const spinner = document.createElement("div");
+  const text = document.createElement("div");
+  const deadline = Date.now() + time * 1e3;
+  loading.id = LOADING_ID;
+  loading.style.cssText = "position:fixed;inset:0;z-index:2147483647;display:flex;flex-direction:column;align-items:center;justify-content:center;background:rgba(0,0,0,.65);color:#fff;font:14px/1.5 sans-serif;";
+  spinner.style.cssText = "width:36px;height:36px;margin-bottom:16px;border:3px solid rgba(255,255,255,.35);border-top-color:#fff;border-radius:50%;animation:vite-build-version-loading .8s linear infinite;";
+  text.textContent = `\u8BF7\u7A0D\u7B49\uFF0C\u6B63\u5728\u68C0\u6D4B\u66F4\u65B0...\uFF08${Math.ceil(time)}\u79D2\uFF09`;
+  const style = document.createElement("style");
+  style.textContent = "@keyframes vite-build-version-loading{to{transform:rotate(360deg)}}";
+  loading.append(style, spinner, text);
+  document.documentElement.appendChild(loading);
+  const countdown = window.setInterval(() => {
+    const seconds = Math.max(0, Math.ceil((deadline - Date.now()) / 1e3));
+    text.textContent = `\u8BF7\u7A0D\u7B49\uFF0C\u6B63\u5728\u68C0\u6D4B\u66F4\u65B0...\uFF08${seconds}\u79D2\uFF09`;
+  }, 1e3);
+  return () => {
+    window.clearInterval(countdown);
+    loading.remove();
+  };
+}
 function createCacheBustedUrl(url) {
   const targetUrl = new URL(url, window.location.href);
   const hash = targetUrl.hash;
@@ -59,18 +84,31 @@ async function clearTargetUrlCache(url) {
 async function clearUrlCache(options = {}) {
   const defaultUrl = window.location.origin + window.location.pathname;
   const urls = options.urls ?? [defaultUrl, createIndexUrl(defaultUrl)];
+  const configuredTime = options.time;
+  const time = typeof configuredTime === "number" && Number.isFinite(configuredTime) && configuredTime > 0 ? configuredTime : DEFAULT_REFRESH_TIME;
   const redirectUrl = new URL(
     options.redirectUrl ?? urls[0] ?? defaultUrl,
     window.location.href
   ).href;
+  const hideLoading = showLoading(time);
+  let refreshTimeout = 0;
   try {
-    for (const url of urls) {
-      try {
-        await clearTargetUrlCache(url);
-      } catch {
-      }
-    }
+    await Promise.race([
+      (async () => {
+        for (const url of urls) {
+          try {
+            await clearTargetUrlCache(url);
+          } catch {
+          }
+        }
+      })(),
+      new Promise((resolve) => {
+        refreshTimeout = window.setTimeout(resolve, time * 1e3);
+      })
+    ]);
   } finally {
+    window.clearTimeout(refreshTimeout);
+    hideLoading();
     window.location.replace(createCacheBustedUrl(redirectUrl));
   }
 }

package/dist/index.cjs

@@ -142,6 +142,9 @@ function serializePayload(payload) {
 function createInjectScript(globalName, payload) {
   return `window[${JSON.stringify(globalName)}] = ${JSON.stringify(payload)};`;
 }
+function createInjectScriptTag(globalName, payload) {
+  return `<script>${createInjectScript(globalName, payload)}</script>`;
+}
 function injectScriptToHead(code, script) {
   const scriptTag = `<script>${script}</script>`;
   if (code.includes(script)) {
@@ -207,6 +210,12 @@ function buildVersionPlugin(options = {}) {
     }
     return injectScriptToHead(code, createInjectScript(globalName, payload));
   };
+  const headScript = () => {
+    if (!injectToHtml || !payload) {
+      return "";
+    }
+    return createInjectScriptTag(globalName, payload);
+  };
   const plugin = {
     name: PLUGIN_NAME,
     config(userConfig, env) {
@@ -290,6 +299,9 @@ function buildVersionPlugin(options = {}) {
   Object.defineProperty(plugin, "transformHtml", {
     value: transformHtml
   });
+  Object.defineProperty(plugin, "headScript", {
+    value: headScript
+  });
   return plugin;
 }
 var index_default = buildVersionPlugin;

package/dist/index.d.cts

@@ -22,6 +22,7 @@ interface BuildVersionPluginOptions {
 }
 type BuildVersionPlugin = Plugin & {
     transformHtml: (code: string, ...args: unknown[]) => string | undefined;
+    headScript: () => string;
 };
 declare function buildVersionPlugin(options?: BuildVersionPluginOptions): BuildVersionPlugin;
 

package/dist/index.d.ts

@@ -22,6 +22,7 @@ interface BuildVersionPluginOptions {
 }
 type BuildVersionPlugin = Plugin & {
     transformHtml: (code: string, ...args: unknown[]) => string | undefined;
+    headScript: () => string;
 };
 declare function buildVersionPlugin(options?: BuildVersionPluginOptions): BuildVersionPlugin;
 

package/dist/index.mjs

@@ -117,6 +117,9 @@ function serializePayload(payload) {
 function createInjectScript(globalName, payload) {
   return `window[${JSON.stringify(globalName)}] = ${JSON.stringify(payload)};`;
 }
+function createInjectScriptTag(globalName, payload) {
+  return `<script>${createInjectScript(globalName, payload)}</script>`;
+}
 function injectScriptToHead(code, script) {
   const scriptTag = `<script>${script}</script>`;
   if (code.includes(script)) {
@@ -182,6 +185,12 @@ function buildVersionPlugin(options = {}) {
     }
     return injectScriptToHead(code, createInjectScript(globalName, payload));
   };
+  const headScript = () => {
+    if (!injectToHtml || !payload) {
+      return "";
+    }
+    return createInjectScriptTag(globalName, payload);
+  };
   const plugin = {
     name: PLUGIN_NAME,
     config(userConfig, env) {
@@ -265,6 +274,9 @@ function buildVersionPlugin(options = {}) {
   Object.defineProperty(plugin, "transformHtml", {
     value: transformHtml
   });
+  Object.defineProperty(plugin, "headScript", {
+    value: headScript
+  });
   return plugin;
 }
 var index_default = buildVersionPlugin;

package/package.json

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