vite-plugin-build-version-file

这篇文档解决什么问题

这个库用来给 Vite 项目提供统一的前端版本信息，适合拿来做这些事情：

• 页面展示当前前端版本
• 检测线上是否有新版本并提示刷新
• 灰度发布时比对本地版本和服务端版本

当前知识库已经在站点配置里用了这个库，所以这不是外部资料，而是当前项目的真实依赖。

当前项目里的实际用法

当前站点在 .vitepress/config.mjs 里直接接入了这个插件：

import { defineConfig } from "vitepress";
import buildVersionPlugin from "vite-plugin-build-version-file";

export default defineConfig({
  vite: {
    plugins: [buildVersionPlugin()],
  },
});

这说明当前站点构建后会产出版本文件，也会在页面里注入版本信息。

安装和适用范围

包名是 vite-plugin-build-version-file。

pnpm add vite-plugin-build-version-file

也可以用：

npm install vite-plugin-build-version-file

适用范围：

• 仅支持 Vite
• 适合 Vue 3 项目
• 要求 vite >= 5
• 要求 node >= 18

最小接入方式

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import buildVersionPlugin from "vite-plugin-build-version-file";

export default defineConfig({
  plugins: [vue(), buildVersionPlugin()],
});

默认会发生什么

默认配置下，插件会做这几件事：

• 开发环境访问 /version.json 时返回版本信息
• 构建完成后在输出目录生成 version.json
• 在 HTML 中注入 window["__VERSION__"]
• 开发环境默认版本号是 0
• 构建环境默认版本号是当前时间戳，格式是 YYYYMMDDHHmmss

构建后的版本文件通常是这样：

{
  "version": "20260401153045",
  "production": true
}

开发环境默认返回：

{
  "version": 0,
  "production": false
}

配置项

filename

• 类型：string
• 默认值："version.json"
• 作用：控制输出文件名

如果写成 meta/version.json，构建后会输出到 dist/meta/version.json，开发环境访问路径也会同步变化。

globalName

• 类型：string
• 默认值："__VERSION__"
• 作用：控制注入到 window 上的属性名

默认注入效果：

<script>
  window["__VERSION__"] = "20260401153045";
</script>

injectToHtml

• 类型：boolean
• 默认值：true
• 作用：是否向 HTML 注入全局变量

设成 false 后，仍然会生成 version.json，只是不会注入 window["__VERSION__"]。

version

• 类型：string | number | ((ctx) => string | number)
• 默认值：开发环境是 0，构建环境是当前时间戳
• 作用：自定义版本号生成逻辑

当传入函数时，会收到：

{
  command: "serve" | "build",
  mode: string,
}

常见用法

使用默认配置

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import buildVersionPlugin from "vite-plugin-build-version-file";

export default defineConfig({
  plugins: [vue(), buildVersionPlugin()],
});

自定义全局变量名

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import buildVersionPlugin from "vite-plugin-build-version-file";

export default defineConfig({
  plugins: [
    vue(),
    buildVersionPlugin({
      globalName: "__APP_VERSION__",
    }),
  ],
});

页面里读取：

const version = window["__APP_VERSION__"];

只保留 version.json

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import buildVersionPlugin from "vite-plugin-build-version-file";

export default defineConfig({
  plugins: [
    vue(),
    buildVersionPlugin({
      injectToHtml: false,
    }),
  ],
});

自定义输出路径

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import buildVersionPlugin from "vite-plugin-build-version-file";

export default defineConfig({
  plugins: [
    vue(),
    buildVersionPlugin({
      filename: "meta/version.json",
    }),
  ],
});

自定义版本号逻辑

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import buildVersionPlugin from "vite-plugin-build-version-file";

export default defineConfig({
  plugins: [
    vue(),
    buildVersionPlugin({
      version: ({ command, mode }) => {
        if (command === "serve") {
          return 0;
        }

        return `${mode}-20260401153045`;
      },
    }),
  ],
});

在项目里怎么读取版本

读取注入到页面里的全局变量

const version = window["__VERSION__"];

读取 version.json

const response = await fetch("/version.json");
const payload = await response.json();

console.log(payload.version);
console.log(payload.production);

这篇文档应该怎么用

• 想快速知道这个库是做什么的，从这里开始
• 想确认当前站点是否已经接入，看上面的实际用法
• 想改文件名、版本号规则或全局变量名，直接看配置项

TIP

如果后面要补“接入步骤”“上线检查”“版本提示刷新流程”，更适合另开一篇放到 playbooks，不要继续堆在这一页。