@aurouscia/vite-app-version

Vite 应用版本标记与检查工具。在构建时自动生成版本时间戳，运行时可检查客户端是否为最新版本。

组成部分

• appVersionMark — Vite 插件，在应用编译时将当前时间戳写入：
  • index.html 的 <meta> 标签里
  • public 目录的静态文件里（部署后可被请求）
• appVersionCheck — 异步函数，在合适的时机进行版本检查，返回客户端是否为最新版

安装

npm install @aurouscia/vite-app-version

使用方法

1. 在 Vite 配置中注册插件

// vite.config.ts
import { defineConfig } from 'vite'
import { appVersionMark } from '@aurouscia/vite-app-version'

export default defineConfig({
  plugins: [
    appVersionMark()
  ]
})

2. 在应用中进行版本检查

// 注意导入路径后面有个 /check
import { appVersionCheck } from '@aurouscia/vite-app-version/check'

// 用户进入特定页面等场景
const isNewest = await appVersionCheck()
if (!isNewest) {
  alert('有新版本，请刷新浏览器更新')
  // 或者直接 location.reload()
}

为什么导入路径不一样？

因为 mark 函数里用到了 Node 的 fs 模块，而 check 函数并不用。
如果从同一个入口导入，Vite 会解析所有依赖项，并对"浏览器使用 fs"（其实并没有）这件事发出警告。

自定义配置

两个函数都接受相同的配置对象，切记要保持一致：

// vite.config.ts
import { defineConfig } from 'vite'
import { appVersionMark } from '@aurouscia/vite-app-version'

export default defineConfig({
  plugins: [
    appVersionMark({
      metaName: 'my-app-version',
      filePath: 'version.txt'
    })
  ]
})

// 页面中
import { appVersionCheck } from '@aurouscia/vite-app-version/check'

const isNewest = await appVersionCheck({
  metaName: 'my-app-version',
  filePath: 'version.txt'
})

配置选项

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | metaName | string | 'vavTimestamp' | 自定义 meta 标签的 name 属性 | | filePath | string | 'vavTimestamp.txt' | 自定义版本文件保存路径（相对于 public 目录，不要以 / 开头） |

开发模式行为

在 Vite 开发服务器（vite dev）运行时：

• meta 标签的 content 始终为 0
• appVersionCheck 检测到 0 后会跳过检查，直接返回 true

这避免了开发时"怎么刷新都显示需要更新"的问题。

构建产物

构建后 public 目录会生成一个版本文件（默认 vavTimestamp.txt），记得将它加入 .gitignore：

# vite-app-version
vavTimestamp.txt

License

MIT