vite-plugin-build-version-file 0.1.8 → 0.1.9

package/README.md

@@ -1,34 +1,33 @@
 # vite-plugin-build-version-file
 
-一个面向 `Vue 3 + Vite` 的构建版本插件。
+一个用于 Vite 项目的构建版本信息插件。
 
-它会在项目运行和构建时提供统一的版本信息：
+它负责在开发态和构建产物中暴露统一的版本信息：
 
-- 构建产物中生成 `version.json`
-- 可选地向 HTML 注入 `window["__VERSION__"]`
-- 支持自定义版本号、文件名、全局变量名和额外数据
+- 开发态通过 dev server 提供 `version.json`
+- 构建后在输出目录生成 `version.json`
+- 普通 Vite HTML 自动注入 `window["__VERSION__"]`
+- VitePress 可通过顶层 `transformHtml` 注入同一份版本信息
+- 支持自定义版本号、输出文件名、全局变量名、时区和额外字段
 
-这个插件只负责产出和暴露版本信息。
+插件只负责生成和暴露版本信息，不负责运行时更新策略。
 
-它不负责这些运行时行为：
+它不会内置这些业务行为：
 
-- 轮询检查版本
-- 弹窗提示用户更新
+- 定时轮询新版本
+- 弹窗提示用户刷新
 - 用户取消后的重试策略
-- 页面刷新时机
-
-适合用在这些场景：
+- 自动刷新页面的时机
 
-- 页面显示当前前端版本
-- 检测线上是否有新版本并提示刷新
-- 灰度发布时对比本地版本和服务端版本
+这些行为通常应放在业务项目中实现。
 
 ## 适用范围
 
-- 仅支持 `Vite`
-- 主要面向 `Vue 3` 项目使用
+- Vite 项目
+- Vue 3 + Vite 项目
+- VitePress 项目
 - `peerDependencies` 要求 `vite >= 5`
-- 运行环境要求 `node >= 18`
+- Node.js 要求 `>= 18`
 
 ## 安装
 
@@ -36,7 +35,7 @@
 pnpm add vite-plugin-build-version-file
 ```
 
-也可以使用：
+也可以使用 npm：
 
 ```bash
 npm install vite-plugin-build-version-file
@@ -44,28 +43,56 @@ npm install vite-plugin-build-version-file
 
 ## 快速开始
 
+### 普通 Vite / Vue 3 项目
+
 ```ts
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
 import buildVersionPlugin from 'vite-plugin-build-version-file'
 
 export default defineConfig({
-  plugins: [vue(), buildVersionPlugin()]
+  plugins: [
+    vue(),
+    buildVersionPlugin()
+  ]
 })
 ```
 
+### VitePress 项目
+
+VitePress 构建 HTML 时不完全走普通 Vite `index.html` 注入链路。需要复用同一个插件实例，并把它的 `transformHtml` 接到 VitePress 顶层配置上。
+
+```js
+import { defineConfig } from 'vitepress'
+import buildVersionPlugin from 'vite-plugin-build-version-file'
+
+const buildVersion = buildVersionPlugin()
+
+export default defineConfig({
+  vite: {
+    plugins: [buildVersion],
+  },
+  transformHtml: buildVersion.transformHtml,
+})
+```
+
+注意：这里必须复用同一个 `buildVersion` 实例。不要分别调用两次 `buildVersionPlugin()`，否则 `transformHtml` 拿不到 Vite 插件阶段生成的 payload。
+
 ## 默认行为
 
-在默认配置下，插件会执行以下行为：
+默认配置下，插件会做这些事：
 
 - 开发态访问 `/version.json` 时返回版本信息
-- 构建后在输出目录生成 `version.json`
-- 构建后的 HTML 中注入 `window["__VERSION__"]`
-- 自动尝试读取业务项目 `package.json` 中的 `name` 和 `version`
+- 构建后输出 `version.json`
+- 向 HTML 注入 `window["__VERSION__"]`
+- 自动读取业务项目最近的 `package.json`
+- 将 `package.json` 的 `name` 写入 `pkgName`
+- 将 `package.json` 的 `version` 写入 `pkgVersion`
 - 开发态默认版本号为 `0`
-- 构建态默认版本号为当前时间戳，格式为 `YYYYMMDDHHmmss`
+- 构建态默认版本号为当前时间，格式为 `YYYYMMDDHHmmss`
+- 默认时区为 `Asia/Shanghai`
 
-默认生成的版本文件内容如下：
+构建态默认输出示例：
 
 ```json
 {
@@ -76,7 +103,7 @@ export default defineConfig({
 }
 ```
 
-开发态默认返回：
+开发态默认输出示例：
 
 ```json
 {
@@ -87,29 +114,6 @@ export default defineConfig({
 }
 ```
 
-## 职责边界
-
-这个库的职责是：
-
-- 生成版本号
-- 输出 `version.json`
-- 向页面注入版本信息
-- 让业务代码能读取当前版本
-
-这些逻辑建议写在业务项目里，而不是放进这个库里：
-
-- 多久检查一次新版本
-- 请求失败后是否重试
-- 用什么 UI 提示用户
-- 用户点击取消后怎么处理
-- 是否立即刷新页面
-
-如果你的项目要做“检测到新版本后提示刷新”，推荐做法是：
-
-- 用 `window["__VERSION__"]` 读取当前页面版本
-- 请求 `version.json` 读取服务端版本
-- 在业务项目里自行决定提示方式和刷新时机
-
 ## 配置项
 
 ```ts
@@ -125,6 +129,8 @@ type BuildVersionPluginOptions = {
   timeZone?: string
   version?: string | number | ((ctx: BuildVersionContext) => string | number)
   data?: Record<string, any>
+  log?: (content: any) => string
+  payload?: (json: any) => any
 }
 ```
 
@@ -132,13 +138,29 @@ type BuildVersionPluginOptions = {
 
 - 类型：`string`
 - 默认值：`"version.json"`
-- 作用：控制输出文件名
+- 作用：控制开发态访问路径和构建态输出文件路径
+
+示例：
+
+```ts
+buildVersionPlugin({
+  filename: 'meta/version.json'
+})
+```
+
+构建后输出：
 
-说明：
+```text
+dist/meta/version.json
+```
 
-- 支持相对路径，例如 `meta/version.json`
-- 构建时会输出到 `dist/meta/version.json`
-- 开发态访问路径也会同步变成对应地址
+开发态访问：
+
+```text
+/meta/version.json
+```
+
+如果项目配置了 Vite `base`，访问路径会自动跟随 `base`。
 
 ### `globalName`
 
@@ -154,18 +176,23 @@ type BuildVersionPluginOptions = {
 </script>
 ```
 
-这里注入的是完整对象，不是单独的版本字符串。
+这里注入的是完整 payload 对象，不是单独版本字符串。
 
 ### `injectToHtml`
 
 - 类型：`boolean`
 - 默认值：`true`
-- 作用：是否向 HTML 注入 `window` 全局变量
+- 作用：控制是否向 HTML 注入 `window["__VERSION__"]`
 
-当设置为 `false` 时：
+设置为 `false` 后，仍会生成和提供 `version.json`。
 
-- 仍然会生成 `version.json`
-- 不会注入 `window["__VERSION__"]`
+### `timeZone`
+
+- 类型：`string`
+- 默认值：`"Asia/Shanghai"`
+- 作用：控制默认构建时间按哪个时区生成
+
+只影响插件默认生成的 `time`。如果你传了 `version`，则以自定义逻辑为准。
 
 ### `version`
 
@@ -173,85 +200,274 @@ type BuildVersionPluginOptions = {
 - 默认值：开发态为 `0`，构建态为当前时间戳
 - 作用：自定义版本号生成逻辑
 
-如果传入函数，函数会收到：
+```ts
+buildVersionPlugin({
+  version: ({ command, mode }) => {
+    if (command === 'serve') {
+      return 0
+    }
+
+    return `${mode}-20260401153045`
+  }
+})
+```
+
+### `data`
+
+- 类型：`Record<string, any>`
+- 默认值：`{}`
+- 作用：向最终 payload 追加自定义字段
 
 ```ts
+buildVersionPlugin({
+  data: {
+    appName: 'admin',
+    gitBranch: 'release/2026-04',
+    commitSha: 'abc1234'
+  }
+})
+```
+
+生成结果示例：
+
+```json
 {
-  command: 'serve' | 'build',
-  mode: string
+  "appName": "admin",
+  "gitBranch": "release/2026-04",
+  "commitSha": "abc1234",
+  "pkgName": "your-app-name",
+  "pkgVersion": "1.0.0",
+  "time": "20260401153045",
+  "env": "production"
 }
 ```
 
-### `timeZone`
+字段覆盖顺序：
 
-- 类型：`string`
-- 默认值：`"Asia/Shanghai"`
-- 作用：控制默认时间按哪个时区生成
+- `data` 会先写入
+- `pkgName`、`pkgVersion` 会使用项目 `package.json` 的值覆盖同名字段
+- `time`、`env` 会使用插件生成的值覆盖同名字段
+- `payload` 可以在最后改写整个结果
 
-说明：
+### `payload`
 
-- 只影响插件默认生成的 `time`
-- 如果构建环境是 UTC，也会按设置的时区输出
-- 如果传了 `version`，则以你自己的 `version` 逻辑为准
+- 类型：`(json: any) => any`
+- 作用：最终改写 payload
 
-### `data`
+适合做字段裁剪、字段重命名或兼容旧系统。
 
-- 类型：`Record<string, any>`
-- 默认值：`{}`
-- 作用：向最终生成的版本信息对象中追加自定义字段
+```ts
+buildVersionPlugin({
+  payload: (json) => ({
+    version: json.time,
+    env: json.env,
+    name: json.pkgName
+  })
+})
+```
 
-说明：
+建议返回对象，避免业务端读取结构不稳定。
 
-- 插件会自动从业务项目的 `package.json` 中读取 `name` 和 `version`，分别写入 `pkgName` 和 `pkgVersion`
-- 查找位置是从当前 Vite 项目根目录开始，向上寻找最近的 `package.json`
-- 会同时影响开发态接口返回、构建产物中的 `version.json` 和注入到 `window` 的对象
-- 如果 `data` 里存在 `time` 或 `env` 同名字段，最终仍以插件生成的值为准
-- 如果 `data` 里存在 `pkgName` 或 `pkgVersion`，读取到业务项目 `package.json` 时会以自动读取的值为准；读取不到时会保留 `data` 里的值
+### `log`
 
-## 使用示例
+- 类型：`(content: any) => string`
+- 作用：自定义构建完成后的控制台输出
 
-### 1. 使用默认配置
+```ts
+buildVersionPlugin({
+  log: (payload) => `build version: ${payload.time}`
+})
+```
+
+## 读取版本信息
+
+### 读取全局变量
 
 ```ts
-import { defineConfig } from 'vite'
-import vue from '@vitejs/plugin-vue'
-import buildVersionPlugin from 'vite-plugin-build-version-file'
+const payload = window['__VERSION__']
 
-export default defineConfig({
-  plugins: [vue(), buildVersionPlugin()]
+console.log(payload.time)
+console.log(payload.env)
+```
+
+适用于需要知道“当前页面构建版本”的场景。
+
+### 读取 `version.json`
+
+```ts
+const response = await fetch('/version.json', {
+  cache: 'no-store'
 })
+const payload = await response.json()
+
+console.log(payload.time)
+console.log(payload.env)
 ```
 
-默认情况下，插件会尝试从业务项目的 `package.json` 中读取：
+适用于和服务器上的最新版本做对比。
 
-- `name` -> `pkgName`
-- `version` -> `pkgVersion`
+## 做版本检查
 
-### 2. 自定义全局变量名
+插件不内置版本检查 UI。推荐业务项目自行处理：
 
-```ts
-import { defineConfig } from 'vite'
-import vue from '@vitejs/plugin-vue'
-import buildVersionPlugin from 'vite-plugin-build-version-file'
+```js
+const CHECK_INTERVAL = 60 * 1000
+const VERSION_URL = '/version.json'
 
-export default defineConfig({
-  plugins: [
-    vue(),
-    buildVersionPlugin({
-      globalName: '__APP_VERSION__'
+async function checkVersion() {
+  try {
+    const response = await fetch(VERSION_URL, {
+      cache: 'no-store'
     })
-  ]
-})
+    const latestPayload = await response.json()
+    const currentPayload = window.__VERSION__
+
+    if (currentPayload && latestPayload.time !== currentPayload.time) {
+      const shouldReload = window.confirm('检测到新版本，是否刷新页面？')
+
+      if (shouldReload) {
+        window.location.reload()
+        return
+      }
+    }
+  } catch (error) {
+    console.warn('check version failed', error)
+  }
+
+  window.setTimeout(checkVersion, CHECK_INTERVAL)
+}
+
+checkVersion()
 ```
 
-注入后可以这样读取：
+建议：
 
-```ts
-const payload = window['__APP_VERSION__']
-const time = payload.time
+- 通常比较 `payload.time` 即可
+- 请求 `version.json` 时使用 `cache: 'no-store'`
+- 轮询间隔不要过短，通常 1 分钟或更长
+- 弹窗、通知、静默刷新等策略放在业务项目里
+- 请求失败后继续下一轮检查，避免一次失败中断流程
+
+## 开发态行为
+
+开发态下，插件不会向业务项目目录写入文件。
+
+它会通过 Vite dev server 直接返回 JSON：
+
+- 不污染 `public/`
+- 不需要生成临时文件
+- 修改插件配置后重启 dev server 即可生效
+
+## 本地开发
+
+仓库提供了两个调试用示例项目：
+
+- 普通 Vite / Vue 3：`debug/fixture-app`
+- VitePress：`debug/vitepress-app`
+- 引用方式：直接引用根目录 `dist/index.mjs`
+
+这意味着示例项目测试的是打包后的真实产物。
+
+```bash
+pnpm install
+pnpm build
+pnpm dev:fixture
+```
+
+调试 VitePress 示例项目：
+
+```bash
+pnpm dev:vitepress
+```
+
+构建示例项目：
+
+```bash
+pnpm build:fixture
+pnpm build:vitepress
+```
+
+## 发布
+
+```bash
+pnpm build
+pnpm build:fixture
+pnpm build:vitepress
+npm publish --access public
+```
+
+发布前建议确认：
+
+- `dist/index.mjs` 已生成
+- `dist/index.cjs` 已生成
+- `dist/index.d.ts` 已生成
+- `debug/fixture-app` 可以正常构建
+- `debug/vitepress-app` 可以正常构建
+- `version.json` 输出正常
+- 普通 Vite HTML 注入正常
+- VitePress `transformHtml` 接入后注入正常
+
+查看最终发包内容：
+
+```bash
+npm pack
+```
+
+正常发布包应只包含：
+
+- `dist`
+- `README.md`
+- `LICENSE`
+- `package.json`
+
+---
+
+# English
+
+`vite-plugin-build-version-file` is a build metadata plugin for Vite projects.
+
+It exposes one consistent version payload in development and production:
+
+- serves `version.json` through the Vite dev server
+- emits `version.json` into the build output directory
+- 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
+
+The plugin only generates and exposes version metadata. It does not decide how your app should check for updates or refresh the page.
+
+It intentionally does not include:
+
+- polling logic
+- update prompts
+- retry rules
+- reload timing
+
+Those behaviors should stay in your application code.
+
+## Compatibility
+
+- Vite projects
+- Vue 3 + Vite projects
+- VitePress projects
+- `vite >= 5`
+- Node.js `>= 18`
+
+## Installation
+
+```bash
+pnpm add vite-plugin-build-version-file
 ```
 
-### 3. 只保留 `version.json`，不注入 `window`
+Or:
+
+```bash
+npm install vite-plugin-build-version-file
+```
+
+## Quick Start
+
+### Vite / Vue 3
 
 ```ts
 import { defineConfig } from 'vite'
@@ -261,168 +477,275 @@ import buildVersionPlugin from 'vite-plugin-build-version-file'
 export default defineConfig({
   plugins: [
     vue(),
-    buildVersionPlugin({
-      injectToHtml: false
-    })
+    buildVersionPlugin()
   ]
 })
 ```
 
-### 4. 自定义输出路径
+### VitePress
 
-```ts
-import { defineConfig } from 'vite'
-import vue from '@vitejs/plugin-vue'
+VitePress does not write production HTML through the same `index.html` flow as a normal Vite app. Reuse one plugin instance and pass its `transformHtml` helper to the top-level VitePress config.
+
+```js
+import { defineConfig } from 'vitepress'
 import buildVersionPlugin from 'vite-plugin-build-version-file'
 
+const buildVersion = buildVersionPlugin()
+
 export default defineConfig({
-  plugins: [
-    vue(),
-    buildVersionPlugin({
-      filename: 'meta/version.json'
-    })
-  ]
+  vite: {
+    plugins: [buildVersion],
+  },
+  transformHtml: buildVersion.transformHtml,
 })
 ```
 
-构建后输出：
+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.
 
-```text
-dist/meta/version.json
+## Default Behavior
+
+With default options, the plugin:
+
+- serves `/version.json` in development
+- emits `version.json` after build
+- injects `window["__VERSION__"]` into HTML
+- reads the nearest project `package.json`
+- writes `name` as `pkgName`
+- writes `version` as `pkgVersion`
+- uses `0` as the development version
+- uses `YYYYMMDDHHmmss` as the production version
+- uses `Asia/Shanghai` as the default time zone
+
+Production payload example:
+
+```json
+{
+  "pkgName": "your-app-name",
+  "pkgVersion": "1.0.0",
+  "time": "20260401153045",
+  "env": "production"
+}
+```
+
+Development payload example:
+
+```json
+{
+  "pkgName": "your-app-name",
+  "pkgVersion": "1.0.0",
+  "time": 0,
+  "env": "development"
+}
 ```
 
-### 5. 自定义版本号生成逻辑
+## Options
 
 ```ts
-import { defineConfig } from 'vite'
-import vue from '@vitejs/plugin-vue'
-import buildVersionPlugin from 'vite-plugin-build-version-file'
+type BuildVersionContext = {
+  command: 'serve' | 'build'
+  mode: string
+}
 
-export default defineConfig({
-  plugins: [
-    vue(),
-    buildVersionPlugin({
-      version: ({ command, mode }) => {
-        if (command === 'serve') {
-          return 0
-        }
+type BuildVersionPluginOptions = {
+  filename?: string
+  globalName?: string
+  injectToHtml?: boolean
+  timeZone?: string
+  version?: string | number | ((ctx: BuildVersionContext) => string | number)
+  data?: Record<string, any>
+  log?: (content: any) => string
+  payload?: (json: any) => any
+}
+```
 
-        return `${mode}-20260401153045`
-      }
-    })
-  ]
+### `filename`
+
+- Type: `string`
+- Default: `"version.json"`
+- Controls the dev URL and build output path.
+
+```ts
+buildVersionPlugin({
+  filename: 'meta/version.json'
 })
 ```
 
-### 6. 指定时区生成时间
+Build output:
+
+```text
+dist/meta/version.json
+```
+
+Development URL:
+
+```text
+/meta/version.json
+```
+
+If your project configures Vite `base`, the URL follows that base.
+
+### `globalName`
+
+- Type: `string`
+- Default: `"__VERSION__"`
+- Controls the property name injected on `window`.
+
+Default injection:
+
+```html
+<script>
+  window["__VERSION__"] = { "time": "20260401153045", "env": "production" };
+</script>
+```
+
+The injected value is the full payload object, not a single version string.
+
+### `injectToHtml`
+
+- Type: `boolean`
+- Default: `true`
+- Controls whether the plugin injects `window["__VERSION__"]`.
+
+When set to `false`, `version.json` is still served and emitted.
+
+### `timeZone`
+
+- Type: `string`
+- Default: `"Asia/Shanghai"`
+- Controls the time zone used by the default production timestamp.
+
+This only affects the default `time`. If you pass `version`, your custom logic wins.
+
+### `version`
+
+- Type: `string | number | ((ctx) => string | number)`
+- Default: `0` in development, current timestamp in production
+- Provides custom version generation.
 
 ```ts
-import { defineConfig } from 'vite'
-import vue from '@vitejs/plugin-vue'
-import buildVersionPlugin from 'vite-plugin-build-version-file'
+buildVersionPlugin({
+  version: ({ command, mode }) => {
+    if (command === 'serve') {
+      return 0
+    }
 
-export default defineConfig({
-  plugins: [
-    vue(),
-    buildVersionPlugin({
-      timeZone: 'Asia/Shanghai'
-    })
-  ]
+    return `${mode}-20260401153045`
+  }
 })
 ```
 
-### 7. 追加自定义数据
+### `data`
 
-```ts
-import { defineConfig } from 'vite'
-import vue from '@vitejs/plugin-vue'
-import buildVersionPlugin from 'vite-plugin-build-version-file'
+- Type: `Record<string, any>`
+- Default: `{}`
+- Adds custom fields to the final payload.
 
-export default defineConfig({
-  plugins: [
-    vue(),
-    buildVersionPlugin({
-      data: {
-        appName: 'admin',
-        gitBranch: 'release/2026-04',
-        commitSha: 'abc1234'
-      }
-    })
-  ]
+```ts
+buildVersionPlugin({
+  data: {
+    appName: 'admin',
+    gitBranch: 'release/2026-04',
+    commitSha: 'abc1234'
+  }
 })
 ```
 
-生成结果示例：
+Example output:
 
 ```json
 {
   "appName": "admin",
   "gitBranch": "release/2026-04",
   "commitSha": "abc1234",
+  "pkgName": "your-app-name",
+  "pkgVersion": "1.0.0",
   "time": "20260401153045",
   "env": "production"
 }
 ```
 
-## 在项目中读取版本
+Merge order:
 
-插件提供两种方式读取版本号，可根据场景选择：
+- `data` is written first
+- `pkgName` and `pkgVersion` from `package.json` override matching fields
+- `time` and `env` from the plugin override matching fields
+- `payload` can rewrite the final object
 
-### 方式一：读取注入的全局变量
+### `payload`
 
-```ts
-const payload = window['__VERSION__']
+- Type: `(json: any) => any`
+- Rewrites the final payload.
 
-console.log(payload.time)
-console.log(payload.env)
+Use it to trim fields, rename fields, or keep compatibility with an older contract.
+
+```ts
+buildVersionPlugin({
+  payload: (json) => ({
+    version: json.time,
+    env: json.env,
+    name: json.pkgName
+  })
+})
 ```
 
-**说明：**
+Returning an object is recommended so application reads stay stable.
 
-- 需要确保 `injectToHtml` 为 `true`（默认值）
-- 这里读到的是完整对象，不是单独字符串
-- 如果配置了 `data`，这里也可以直接读取对应字段
+### `log`
 
-### 方式二：读取 `version.json`
+- Type: `(content: any) => string`
+- Customizes the build-complete console output.
 
 ```ts
-const response = await fetch('/version.json')
-const payload = await response.json()
+buildVersionPlugin({
+  log: (payload) => `build version: ${payload.time}`
+})
+```
+
+## Reading Version Metadata
+
+### Read the injected global
+
+```ts
+const payload = window['__VERSION__']
 
 console.log(payload.time)
 console.log(payload.env)
 ```
 
-如果你配置了自定义 `filename`，这里的请求路径也需要改成对应地址。
+Use this when you need the version of the currently loaded page.
 
-如果你配置了 `data`，返回结果中也会包含这些额外字段。
+### Read `version.json`
 
-默认情况下，如果业务项目存在 `package.json`，返回结果中也会包含：
+```ts
+const response = await fetch('/version.json', {
+  cache: 'no-store'
+})
+const payload = await response.json()
 
-- `pkgName`
-- `pkgVersion`
+console.log(payload.time)
+console.log(payload.env)
+```
 
-## 在项目中做版本检查
+Use this when you need to compare the current page against the latest deployed version.
 
-推荐把“检查新版本并提示刷新”的逻辑写在业务项目里。
+## Checking for Updates
 
-通用伪代码：
+The plugin does not include update-checking UI. Keep that logic in your app.
 
 ```js
 const CHECK_INTERVAL = 60 * 1000
-const VERSION_URL = `${import.meta.env.VITE_BASE_PATH}/version.json`
+const VERSION_URL = '/version.json'
 
 async function checkVersion() {
   try {
     const response = await fetch(VERSION_URL, {
       cache: 'no-store'
     })
-
-    const payload = await response.json()
+    const latestPayload = await response.json()
     const currentPayload = window.__VERSION__
 
-    if (currentPayload && payload.time !== currentPayload.time) {
-      const shouldReload = await showUpdatePrompt()
+    if (currentPayload && latestPayload.time !== currentPayload.time) {
+      const shouldReload = window.confirm('A new version is available. Reload now?')
 
       if (shouldReload) {
         window.location.reload()
@@ -433,126 +756,86 @@ async function checkVersion() {
     console.warn('check version failed', error)
   }
 
-  scheduleNextCheck()
-}
-
-function scheduleNextCheck() {
-  setTimeout(checkVersion, CHECK_INTERVAL)
-}
-
-function showUpdatePrompt() {
-  // 这里替换成你自己的弹窗、消息组件或确认框
-  return Promise.resolve(window.confirm('检测到新版本，是否刷新页面？'))
+  window.setTimeout(checkVersion, CHECK_INTERVAL)
 }
 
 checkVersion()
 ```
 
-建议：
-
-- 版本比较只判断 `payload.time` 和当前页面里的 `window.__VERSION__.time` 是否一致
-- 提示方式由业务项目自己决定，可以是弹窗、消息条、通知或静默刷新
-- 轮询间隔不要过短，通常用 1 分钟或更长更合适
-- 请求失败后继续下一轮检查，避免一次失败后整个流程中断
-
-上面这段逻辑故意没有放进插件里，因为不同项目通常会有不同要求：
+Recommendations:
 
-- 轮询频率不同
-- 请求路径可能不同
-- 弹窗组件不同
-- 刷新策略不同
-- 失败重试策略不同
+- 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.
 
-## 开发态行为说明
+## Development Behavior
 
-开发态下，插件不会往项目的 `public/` 目录写文件。
+In development, the plugin does not write files into your project directory.
 
-它会直接通过 Vite dev server 返回版本 JSON，因此：
+It serves JSON directly through the Vite dev server:
 
-- 不会污染业务项目目录
-- 更适合本地调试
-- 修改配置后重新启动 dev server 即可看到结果
+- no `public/` pollution
+- no temporary file generation
+- restart the dev server after changing plugin options
 
-如果项目配置了 `base`，版本文件访问路径会自动跟随 `base`。
+## Local Development
 
-## 本地开发与联调
+The repository contains two fixture apps:
 
-仓库中已经提供了一个专门用于调试的 `Vite + Vue 3` 测试项目：
+- Vite / Vue 3: `debug/fixture-app`
+- VitePress: `debug/vitepress-app`
+- They import the built package from `dist/index.mjs`
 
-- 路径：`debug/fixture-app`
-- 引用方式：直接引用根目录 `dist/index.mjs`
-
-这意味着它测试的是“打包后的真实产物”，而不是源码直连。
-
-### 安装依赖
+This verifies the real build output instead of importing source files directly.
 
 ```bash
 pnpm install
-```
-
-### 构建插件
-
-```bash
 pnpm build
-```
-
-### 启动测试项目
-
-```bash
 pnpm dev:fixture
 ```
 
-启动后可以在页面里直接看到：
-
-- `window["__VERSION__"]`
-- `/version.json` 的返回结果
-
-### 构建测试项目
+Run the VitePress fixture:
 
 ```bash
-pnpm build:fixture
+pnpm dev:vitepress
 ```
 
-这个命令会先构建插件，再构建测试项目，用来验证 `dist` 产物能否被正常消费。
-
-## 发布到 npm
-
-### 1. 登录 npm
+Build fixture apps:
 
 ```bash
-npm login
+pnpm build:fixture
+pnpm build:vitepress
 ```
 
-### 2. 构建并验证
+## Publishing
 
 ```bash
 pnpm build
 pnpm build:fixture
-```
-
-### 3. 发布公开包
-
-```bash
+pnpm build:vitepress
 npm publish --access public
 ```
 
-## 发布前检查建议
+Before publishing, check:
 
-发布前建议至少确认以下几点：
-
-- `dist/index.mjs`、`dist/index.cjs`、`dist/index.d.ts` 已生成
-- `debug/fixture-app` 可以正常运行或构建
-- `version.json` 输出正常
-- HTML 注入结果符合预期
-- `package.json` 中的 `name`、`version`、`exports`、`publishConfig` 正确
+- `dist/index.mjs`
+- `dist/index.cjs`
+- `dist/index.d.ts`
+- fixture app build
+- VitePress fixture build
+- `version.json` output
+- normal Vite HTML injection
+- VitePress `transformHtml` injection
 
-如果你要进一步检查最终发布内容，可以执行：
+Inspect the publish package:
 
 ```bash
 npm pack
 ```
 
-正常情况下，发布包中应只包含：
+The package should contain:
 
 - `dist`
 - `README.md`

package/dist/index.cjs

@@ -129,6 +129,19 @@ function serializePayload(payload) {
   return `${JSON.stringify(payload, null, 2)}
 `;
 }
+function createInjectScript(globalName, payload) {
+  return `window[${JSON.stringify(globalName)}] = ${JSON.stringify(payload)};`;
+}
+function injectScriptToHead(code, script) {
+  const scriptTag = `<script>${script}</script>`;
+  if (code.includes(script)) {
+    return code;
+  }
+  if (code.includes("</head>")) {
+    return code.replace("</head>", `${scriptTag}</head>`);
+  }
+  return `${scriptTag}${code}`;
+}
 function parsePathname(requestUrl) {
   if (!requestUrl) {
     return "/";
@@ -171,7 +184,13 @@ function buildVersionPlugin(options = {}) {
   const timeZone = normalizeTimeZone(options.timeZone ?? DEFAULT_TIME_ZONE);
   const data = normalizeData(options.data);
   let payload;
-  return {
+  const transformHtml = (code, ..._args) => {
+    if (!injectToHtml || !payload) {
+      return void 0;
+    }
+    return injectScriptToHead(code, createInjectScript(globalName, payload));
+  };
+  const plugin = {
     name: PLUGIN_NAME,
     configResolved(config) {
       const context = {
@@ -207,7 +226,7 @@ function buildVersionPlugin(options = {}) {
         {
           tag: "script",
           injectTo: "head",
-          children: `window[${JSON.stringify(globalName)}] = ${JSON.stringify(payload)};`
+          children: createInjectScript(globalName, payload)
         }
       ];
       return tags;
@@ -229,6 +248,10 @@ function buildVersionPlugin(options = {}) {
       }
     }
   };
+  Object.defineProperty(plugin, "transformHtml", {
+    value: transformHtml
+  });
+  return plugin;
 }
 var index_default = buildVersionPlugin;
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.d.cts

@@ -19,6 +19,9 @@ interface BuildVersionPluginOptions {
     log?: (content: any) => string;
     payload?: (json: any) => any;
 }
-declare function buildVersionPlugin(options?: BuildVersionPluginOptions): Plugin;
+type BuildVersionPlugin = Plugin & {
+    transformHtml: (code: string, ...args: unknown[]) => string | undefined;
+};
+declare function buildVersionPlugin(options?: BuildVersionPluginOptions): BuildVersionPlugin;
 
-export { type BuildVersionContext, type BuildVersionPayload, type BuildVersionPluginOptions, buildVersionPlugin, buildVersionPlugin as default };
+export { type BuildVersionContext, type BuildVersionPayload, type BuildVersionPlugin, type BuildVersionPluginOptions, buildVersionPlugin, buildVersionPlugin as default };

package/dist/index.d.ts

@@ -19,6 +19,9 @@ interface BuildVersionPluginOptions {
     log?: (content: any) => string;
     payload?: (json: any) => any;
 }
-declare function buildVersionPlugin(options?: BuildVersionPluginOptions): Plugin;
+type BuildVersionPlugin = Plugin & {
+    transformHtml: (code: string, ...args: unknown[]) => string | undefined;
+};
+declare function buildVersionPlugin(options?: BuildVersionPluginOptions): BuildVersionPlugin;
 
-export { type BuildVersionContext, type BuildVersionPayload, type BuildVersionPluginOptions, buildVersionPlugin, buildVersionPlugin as default };
+export { type BuildVersionContext, type BuildVersionPayload, type BuildVersionPlugin, type BuildVersionPluginOptions, buildVersionPlugin, buildVersionPlugin as default };

package/dist/index.mjs

@@ -104,6 +104,19 @@ function serializePayload(payload) {
   return `${JSON.stringify(payload, null, 2)}
 `;
 }
+function createInjectScript(globalName, payload) {
+  return `window[${JSON.stringify(globalName)}] = ${JSON.stringify(payload)};`;
+}
+function injectScriptToHead(code, script) {
+  const scriptTag = `<script>${script}</script>`;
+  if (code.includes(script)) {
+    return code;
+  }
+  if (code.includes("</head>")) {
+    return code.replace("</head>", `${scriptTag}</head>`);
+  }
+  return `${scriptTag}${code}`;
+}
 function parsePathname(requestUrl) {
   if (!requestUrl) {
     return "/";
@@ -146,7 +159,13 @@ function buildVersionPlugin(options = {}) {
   const timeZone = normalizeTimeZone(options.timeZone ?? DEFAULT_TIME_ZONE);
   const data = normalizeData(options.data);
   let payload;
-  return {
+  const transformHtml = (code, ..._args) => {
+    if (!injectToHtml || !payload) {
+      return void 0;
+    }
+    return injectScriptToHead(code, createInjectScript(globalName, payload));
+  };
+  const plugin = {
     name: PLUGIN_NAME,
     configResolved(config) {
       const context = {
@@ -182,7 +201,7 @@ function buildVersionPlugin(options = {}) {
         {
           tag: "script",
           injectTo: "head",
-          children: `window[${JSON.stringify(globalName)}] = ${JSON.stringify(payload)};`
+          children: createInjectScript(globalName, payload)
         }
       ];
       return tags;
@@ -204,6 +223,10 @@ function buildVersionPlugin(options = {}) {
       }
     }
   };
+  Object.defineProperty(plugin, "transformHtml", {
+    value: transformHtml
+  });
+  return plugin;
 }
 var index_default = buildVersionPlugin;
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-build-version-file",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "A Vite plugin that emits version.json and injects version metadata into HTML.",
   "license": "MIT",
   "type": "module",
@@ -23,7 +23,9 @@
   "scripts": {
     "build": "tsup --config tsup.config.ts",
     "build:fixture": "pnpm build && vite build --config debug/fixture-app/vite.config.ts",
+    "build:vitepress": "pnpm build && vitepress build debug/vitepress-app",
     "dev:fixture": "pnpm build && vite --config debug/fixture-app/vite.config.ts",
+    "dev:vitepress": "pnpm build && vitepress dev debug/vitepress-app",
     "prepublishOnly": "pnpm build:fixture"
   },
   "keywords": [
@@ -49,6 +51,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
     "vite": "^5.0.0",
+    "vitepress": "^1.6.4",
     "vue": "^3.4.0"
   }
 }