vite-plugin-build-version-file 0.1.2 → 0.1.4

package/README.md

@@ -6,8 +6,18 @@
 
 - 构建产物中生成 `version.json`
 - 可选地向 HTML 注入 `window["__VERSION__"]`
+- 通过 `import.meta.env.__VERSION__` 在代码中直接读取版本号
 - 支持自定义版本号、文件名和全局变量名
 
+这个插件只负责产出和暴露版本信息。
+
+它不负责这些运行时行为：
+
+- 轮询检查版本
+- 弹窗提示用户更新
+- 用户取消后的重试策略
+- 页面刷新时机
+
 适合用在这些场景：
 
 - 页面显示当前前端版本
@@ -60,7 +70,7 @@ export default defineConfig({
 ```json
 {
   "version": "20260401153045",
-  "production": true
+  "env": "production"
 }
 ```
 
@@ -69,10 +79,33 @@ export default defineConfig({
 ```json
 {
   "version": 0,
-  "production": false
+  "env": "development"
 }
 ```
 
+## 职责边界
+
+这个库的职责是：
+
+- 生成版本号
+- 输出 `version.json`
+- 向页面注入版本信息
+- 让业务代码能读取当前版本
+
+这些逻辑建议写在业务项目里，而不是放进这个库里：
+
+- 多久检查一次新版本
+- 请求失败后是否重试
+- 用什么 UI 提示用户
+- 用户点击取消后怎么处理
+- 是否立即刷新页面
+
+如果你的项目要做“检测到新版本后提示刷新”，推荐做法是：
+
+- 用 `import.meta.env.__VERSION__` 读取当前页面版本
+- 请求 `version.json` 读取服务端版本
+- 在业务项目里自行决定提示方式和刷新时机
+
 ## 配置项
 
 ```ts
@@ -111,10 +144,12 @@ type BuildVersionPluginOptions = {
 
 ```html
 <script>
-  window["__VERSION__"] = "20260401153045";
+  window["__VERSION__"] = { "version": "20260401153045", "env": "production" };
 </script>
 ```
 
+这里注入的是完整对象，不是单独的版本字符串。
+
 ### `injectToHtml`
 
 - 类型：`boolean`
@@ -175,7 +210,8 @@ export default defineConfig({
 注入后可以这样读取：
 
 ```ts
-const version = window['__APP_VERSION__']
+const payload = window['__APP_VERSION__']
+const version = payload.version
 ```
 
 ### 3. 只保留 `version.json`，不注入 `window`
@@ -243,24 +279,95 @@ export default defineConfig({
 
 ## 在项目中读取版本
 
-### 读取注入的全局变量
+插件提供三种方式读取版本号，可根据场景选择：
+
+### 方式一：通过 `import.meta.env` 读取（推荐）
+
+版本号会被注入到 `import.meta.env` 中，可以直接在代码中使用：
+
+```ts
+const version = import.meta.env.__VERSION__
+console.log(version) // '20260401153045' 或 '1.2.3'
+```
+
+**优势：**
+- 无需等待页面加载或发起请求
+- 类型安全，可在 `vite-env.d.ts` 中声明类型
+- 适合在应用初始化时读取版本
+
+**TypeScript 类型声明：**
+
+```ts
+// vite-env.d.ts
+interface ImportMetaEnv {
+  readonly __VERSION__: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}
+```
+
+### 方式二：读取注入的全局变量
 
 ```ts
-const version = window['__VERSION__']
+const payload = window['__VERSION__']
+
+console.log(payload.version)
+console.log(payload.env)
 ```
 
-### 读取 `version.json`
+**说明：**
+
+- 需要确保 `injectToHtml` 为 `true`（默认值）
+- 这里读到的是完整对象，不是单独字符串
+
+### 方式三：读取 `version.json`
 
 ```ts
 const response = await fetch('/version.json')
 const payload = await response.json()
 
 console.log(payload.version)
-console.log(payload.production)
+console.log(payload.env)
 ```
 
 如果你配置了自定义 `filename`，这里的请求路径也需要改成对应地址。
 
+## 在项目中做版本检查
+
+推荐把“检查新版本并提示刷新”的逻辑写在业务项目里。
+
+示例：
+
+```ts
+async function checkVersion() {
+  const response = await fetch(import.meta.env.VITE_BASE_PATH + '/version.json')
+  const payload = await response.json()
+
+  if (payload.version !== import.meta.env.__VERSION__) {
+    const shouldReload = window.confirm('检测到新版本，是否刷新页面？')
+
+    if (shouldReload) {
+      window.location.reload()
+      return
+    }
+  }
+
+  setTimeout(checkVersion, 1000)
+}
+
+checkVersion()
+```
+
+上面这段逻辑故意没有放进插件里，因为不同项目通常会有不同要求：
+
+- 轮询频率不同
+- 请求路径可能不同
+- 弹窗组件不同
+- 刷新策略不同
+- 失败重试策略不同
+
 ## 开发态行为说明
 
 开发态下，插件不会往项目的 `public/` 目录写文件。

package/dist/index.cjs

@@ -114,7 +114,7 @@ function buildVersionPlugin(options = {}) {
       }
       payload = {
         version,
-        production: config.command === "build"
+        env: config.mode
       };
       if (options.payload) {
         payload = options.payload(payload);

package/dist/index.d.cts

@@ -6,7 +6,7 @@ interface BuildVersionContext {
 }
 interface BuildVersionPayload {
     version: string | number;
-    production: boolean;
+    env: string;
 }
 interface BuildVersionPluginOptions {
     filename?: string;

package/dist/index.d.ts

@@ -6,7 +6,7 @@ interface BuildVersionContext {
 }
 interface BuildVersionPayload {
     version: string | number;
-    production: boolean;
+    env: string;
 }
 interface BuildVersionPluginOptions {
     filename?: string;

package/dist/index.mjs

@@ -89,7 +89,7 @@ function buildVersionPlugin(options = {}) {
       }
       payload = {
         version,
-        production: config.command === "build"
+        env: config.mode
       };
       if (options.payload) {
         payload = options.payload(payload);

package/package.json

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