vite-plugin-build-version-file 0.1.17 → 0.2.0

package/README.md

@@ -5,7 +5,9 @@
 它负责在开发态和构建产物中暴露统一的版本信息：
 
 - 开发态通过 dev server 提供 `version.json`
+- 开发态通过 dev server 提供 `loading.html`，便于本地调试
 - 构建后在输出目录生成 `version.json`
+- 构建后生成与 `index.html` 同级的 `loading.html` 缓存清理页
 - 普通 Vite HTML 自动注入 `window["__VERSION__"]`
 - 可选通过 `define` 将同一份 payload 编译进 JS 产物
 - VitePress 可通过顶层 `transformHtml` 注入同一份版本信息
@@ -27,6 +29,7 @@
 - Vite 项目
 - Vue 3 + Vite 项目
 - VitePress 项目
+- Nuxt 项目（需自行接 `render:html`，见下）
 - `peerDependencies` 要求 `vite >= 5`
 - Node.js 要求 `>= 18`
 
@@ -81,12 +84,40 @@ 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` emit 到该目录，因此 Nuxt 打包后的静态产物会包含这个文件。默认文件路径为 `/_nuxt/version.json`；如果需要固定使用根路径 `/version.json`，请将文件复制到 Nuxt `public` 目录，或在构建后自行复制。
+
 ## 默认行为
 
 默认配置下，插件会做这些事：
 
 - 开发态访问 `/version.json` 时返回版本信息
 - 构建后输出 `version.json`
+- 构建后输出 `loading.html`
 - 向 HTML 注入 `window["__VERSION__"]`
 - 自动读取业务项目最近的 `package.json`
 - 将 `package.json` 的 `name` 写入 `pkgName`
@@ -127,6 +158,7 @@ type BuildVersionContext = {
 
 type BuildVersionPluginOptions = {
   filename?: string
+  loadingPage?: string | false
   globalName?: string
   defineName?: string | false
   injectToHtml?: boolean
@@ -166,6 +198,30 @@ dist/meta/version.json
 
 如果项目配置了 Vite `base`，访问路径会自动跟随 `base`。
 
+### `loadingPage`
+
+- 类型：`string | false`
+- 默认值：`"loading"`
+- 作用：控制构建产物中缓存清理页的文件名
+
+默认输出 `loading.html`，与 `index.html` 同级。值不带后缀时会自动补 `.html`，也支持子路径：
+
+```ts
+buildVersionPlugin({
+  loadingPage: 'cache/loading'
+})
+```
+
+构建后输出：
+
+```text
+dist/cache/loading.html
+```
+
+传 `false` 时不生成该页面。
+
+Nuxt 下与 `version.json` 使用同一规则，默认输出到 `_nuxt/loading.html`；如果需要固定使用根路径 `/loading.html`，请将文件复制到 Nuxt `public` 目录，或在构建后自行复制。
+
 ### `globalName`
 
 - 类型：`string`
@@ -342,91 +398,187 @@ 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`；不要在多个组件中各自维护一份弹窗状态。
 
 ## 刷新指定项目缓存
 
 ```ts
-import { clearUrlCache } from 'vite-plugin-build-version-file/client'
+import { redirectToLoading } from 'vite-plugin-build-version-file/client'
 
-await clearUrlCache({
+redirectToLoading({
   urls: ['/vue-app/', '/vue-app/index.html'],
   redirectUrl: '/vue-app/',
-  time: 5
+  time: 5,
+  times: 2,
+  title: '正在清理缓存',
+  filename: 'loading.html'
 })
 ```
 
-调用后会显示全屏 loading 和刷新倒计时。`time` 单位为秒，默认值为 `5`；缓存处理提前完成时会立即刷新，到达时限后则无论调用结果如何都会刷新。
+`redirectToLoading` 只负责携带参数跳转到构建产物中的 `loading.html`，不向当前页面注入任何 DOM，也不在主页面执行清理逻辑。缓存清理与跳转全部发生在 `loading.html` 内：
+
+- 打开后立即执行清理，并显示全屏 loading
+- 缓存处理提前完成时会立即跳转；到达 `time` 时限（单位秒，默认 `5`）后无论调用结果如何都会跳转
+- 跳转发生在 `loading.html` 内，主页面代码无需等待
 
-参数对象可省略。无参时按顺序检测以下两组 URL：
+参数对象可省略：
+
+```ts
+redirectToLoading()
+```
+
+无参时按顺序检测以下两组 URL：
 
 1. `location.origin + location.pathname`
 2. 第一组 URL 拼接 `index.html`
 
-两组完成后，默认携带随机时间戳跳转到第一组 URL：
+完成后跳转回 `window.location.href`（query 与 hash 原样保留，不追加缓存戳）。
+
+参数说明：
+
+- `urls`：需要清理缓存的 URL 列表，可传多个。默认如上两条
+- `redirectUrl`：清理完成或超时后跳转的目标 URL。默认为调用时的 `window.location.href`
+- `time`：最长等待秒数，默认 `5`
+- `times`：整套清理操作重复执行的次数，默认 `2`
+- `title`：传入后在 loading 页中心显示该文案；不传只显示 loading 图标
+- `filename`：`loading.html` 的路径，默认 `loading.html`，相对当前页面解析
+
+除 `filename` 外的参数会合并成一个 JSON 对象，写在随机参数名的 query 参数下；loading 页按参数值解析，不依赖参数名。
+
+loading 页默认透明背景，不遮挡页面底色；`title` 传了才显示文字。
+
+仍然可以用旧名调用，行为一致：
 
 ```ts
-await clearUrlCache()
+import { clearUrlCache } from 'vite-plugin-build-version-file/client'
+
+clearUrlCache({ urls: ['/vue-app/'] })
 ```
 
-Vue hash 路由会原样保留，缓存时间戳写在 `#` 前，确保服务器能够收到：
+Vue hash 路由会原样保留。缓存戳只加在 loading 页内部的 fetch / iframe 请求上，用于绕过旧缓存；最终跳转地址原样使用，不附加任何参数：
 
 ```text
-https://xxxx/pc/?_=随机值#/login?redirect=/dashboard/analysis
+调用页：https://xxxx/pc/#/login?redirect=/dashboard/analysis
+清理请求：https://xxxx/pc/?随机参数名=随机值
+最终跳转：https://xxxx/pc/#/login?redirect=/dashboard/analysis
 ```
 
-该方法仅支持同源 URL。它会绕过缓存请求 URL、强制刷新原 URL、通过隐藏 iframe 再次加载页面，最后携带随机时间戳跳转到该 URL。创建 iframe 前会销毁同一页面中已有的缓存刷新 iframe。单次请求或 iframe 加载失败不会阻断最终跳转。
+`loading.html` 内仅支持同源 URL。它会绕过缓存请求 URL、强制刷新原 URL、通过隐藏 iframe 再次加载页面，最后跳转到目标 URL（不附加缓存戳）。创建 iframe 前会销毁同一页面中已有的缓存刷新 iframe。单次请求或 iframe 加载失败不会阻断最终跳转。
 
 受浏览器限制，前端代码无法直接删除指定 URL 下的全部 HTTP 缓存；该方法只能尽可能刷新对应 Vue 项目的缓存。
 
+直接打开 `loading.html` 且不带 query 时，默认以 `loading.html` 所在目录作为应用根路径执行同一套清理。
+
 ## 开发态行为
 
 开发态下，插件不会向业务项目目录写入文件。
 
-它会通过 Vite dev server 直接返回 JSON：
+它会通过 Vite dev server 直接返回，不落文件：
 
+- `version.json`：版本信息 JSON
+- `loading.html`：与构建态同路径规则（可用 `loadingPage` 调整），可直接在浏览器打开调试清理与跳转流程
 - 不污染 `public/`
 - 不需要生成临时文件
 - 修改插件配置后重启 dev server 即可生效
 
+调试 loading 页时，query 参数与构建态一致：参数名随机，值是包含 `urls` 的 JSON，例如：
+
+```text
+http://localhost:5173/loading.html?x7k2q9={"urls":["http://localhost:5173/","http://localhost:5173/index.html"],"redirectUrl":"http://localhost:5173/","time":5,"times":2,"title":"调试"}
+```
+
+也可以直接打开 `http://localhost:5173/loading.html`，按所在目录执行默认清理。
+
 ## 本地开发
 
 仓库提供了两个调试用示例项目：
@@ -468,6 +620,7 @@ npm pack --dry-run
 建议检查：
 
 - `debug/fixture-app/dist/version.json` 包含 `time`、`env`、`pkgName`、`pkgVersion`
+- `debug/fixture-app/dist/loading.html` 与 `index.html` 同级生成
 - `debug/fixture-app/dist/index.html` 只注入一次 `window["__VERSION__"]`
 - `debug/vitepress-app/.vitepress/dist/meta/version.json` 包含 `fixture`、`time`、`env`
 - VitePress 每个 HTML 只注入一次 `window["__VERSION__"]`
@@ -516,7 +669,9 @@ npm pack
 It exposes one consistent version payload in development and production:
 
 - serves `version.json` through the Vite dev server
+- serves `loading.html` through the Vite dev server for local debugging
 - emits `version.json` into the build output directory
+- emits a `loading.html` cache-clearing page next to `index.html`
 - injects `window["__VERSION__"]` into normal Vite HTML
 - supports VitePress through its top-level `transformHtml` hook
 - supports custom versions, filenames, global variable names, time zones, and extra payload fields
@@ -537,6 +692,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`
 
@@ -591,12 +747,40 @@ 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.
+
+The plugin automatically detects Nuxt's build assets directory and emits `version.json` there, so Nuxt's static output includes the file. The default URL is `/_nuxt/version.json`; if the file must stay at `/version.json`, copy it into Nuxt's `public` directory or copy it after the build.
+
 ## Default Behavior
 
 With default options, the plugin:
 
 - serves `/version.json` in development
 - emits `version.json` after build
+- emits `loading.html` after build
 - injects `window["__VERSION__"]` into HTML
 - reads the nearest project `package.json`
 - writes `name` as `pkgName`
@@ -637,6 +821,7 @@ type BuildVersionContext = {
 
 type BuildVersionPluginOptions = {
   filename?: string
+  loadingPage?: string | false
   globalName?: string
   injectToHtml?: boolean
   timeZone?: string
@@ -673,6 +858,30 @@ Development URL:
 
 If your project configures Vite `base`, the URL follows that base.
 
+### `loadingPage`
+
+- Type: `string | false`
+- Default: `"loading"`
+- Controls the filename of the cache-clearing page in the build output.
+
+The default emits `loading.html` next to `index.html`. When the value has no suffix, `.html` is appended; sub-paths are supported:
+
+```ts
+buildVersionPlugin({
+  loadingPage: 'cache/loading'
+})
+```
+
+Build output:
+
+```text
+dist/cache/loading.html
+```
+
+Pass `false` to skip emitting the page.
+
+Nuxt uses the same rule as `version.json` and emits `_nuxt/loading.html` by default. If the file must stay at `/loading.html`, copy it into Nuxt's `public` directory or copy it after the build.
+
 ### `globalName`
 
 - Type: `string`
@@ -819,91 +1028,187 @@ 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
 
 ```ts
-import { clearUrlCache } from 'vite-plugin-build-version-file/client'
+import { redirectToLoading } from 'vite-plugin-build-version-file/client'
 
-await clearUrlCache({
+redirectToLoading({
   urls: ['/vue-app/', '/vue-app/index.html'],
   redirectUrl: '/vue-app/',
-  time: 5
+  time: 5,
+  times: 2,
+  title: 'Clearing cache',
+  filename: 'loading.html'
 })
 ```
 
-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.
+`redirectToLoading` only builds the query string and navigates to the `loading.html` emitted by the build. It injects nothing into the current page and runs no cleanup logic there. Cache clearing and navigation both happen inside `loading.html`:
+
+- cleanup starts as soon as the page opens, with a full-screen loading mask
+- navigation happens as soon as cleanup finishes; once `time` seconds (default `5`) elapse, it happens regardless of the result
+- navigation is triggered inside `loading.html`, so the host page does not wait
 
-The options object is optional. Without arguments, the following URL groups are checked in order:
+The options object is optional:
+
+```ts
+redirectToLoading()
+```
+
+Without arguments, the following URL groups are checked in order:
 
 1. `location.origin + location.pathname`
 2. The first URL with `index.html` appended
 
-After both groups complete, the method navigates to the first URL with a random timestamp:
+After both groups complete, navigation goes back to the caller's `window.location.href`; query and hash are preserved and no cache-busting parameter is appended.
+
+Options:
+
+- `urls`: cache-clearing targets; multiple URLs are supported
+- `redirectUrl`: target after cleanup or timeout; defaults to `window.location.href` at call time
+- `time`: maximum wait in seconds, default `5`
+- `times`: how many times the whole cleanup pass runs, default `2`
+- `title`: when provided, shows that text in the loading page center; when omitted, only the loading icon is shown
+- `filename`: path of the loading page, default `loading.html`, resolved against the current page
+
+Every value except `filename` is merged into a single JSON object placed under a randomly named query parameter; the loading page parses values, not parameter names.
+
+The loading page uses a transparent background by default, and only shows text when `title` is provided.
+
+The old name still works and behaves the same:
 
 ```ts
-await clearUrlCache()
+import { clearUrlCache } from 'vite-plugin-build-version-file/client'
+
+clearUrlCache({ urls: ['/vue-app/'] })
 ```
 
-Vue hash routes are preserved. The cache-busting timestamp is added before `#` so the server receives it:
+Vue hash routes are preserved. Cache-busting parameters are added only to the fetch / iframe requests made by the loading page; the final navigation target stays exactly as given:
 
 ```text
-https://xxx.cn/pc/?_=random-value#/login?redirect=/dashboard/analysis
+caller: https://xxx.cn/pc/#/login?redirect=/dashboard/analysis
+cleanup request: https://xxx.cn/pc/?random-key=random-value
+final navigation: https://xxx.cn/pc/#/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.
+`loading.html` 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 target URL without any cache-busting parameter. 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.
 
+Opening `loading.html` directly without a query string treats the page's own directory as the application root and runs the same cleanup flow.
+
 ## Development Behavior
 
 In development, the plugin does not write files into your project directory.
 
-It serves JSON directly through the Vite dev server:
+It serves content directly through the Vite dev server without writing files:
 
+- `version.json`: the version payload as JSON
+- `loading.html`: the same cache-clearing page as the build output (path configured by `loadingPage`), so you can open it directly in the browser to debug the cleanup and navigation flow
 - no `public/` pollution
 - no temporary file generation
 - restart the dev server after changing plugin options
 
+The loading page accepts the same query parameters in development: the parameter name is random and the value is JSON containing `urls`, for example:
+
+```text
+http://localhost:5173/loading.html?x7k2q9={"urls":["http://localhost:5173/","http://localhost:5173/index.html"],"redirectUrl":"http://localhost:5173/","time":5,"times":2,"title":"debug"}
+```
+
+You can also open `http://localhost:5173/loading.html` directly to run the default cleanup for its own directory.
+
 ## Local Development
 
 The repository contains two fixture apps:
@@ -945,6 +1250,7 @@ npm pack --dry-run
 Check:
 
 - `debug/fixture-app/dist/version.json` contains `time`, `env`, `pkgName`, and `pkgVersion`
+- `debug/fixture-app/dist/loading.html` is emitted next to `index.html`
 - `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