vite-plugin-version-mark

August 5, 2025 · View on GitHub

中文 | English

vite-plugin-version-mark

Vite/Nuxt插件，能自动将版本信息（如package.json中的版本号、Git SHA值或自定义命令）通过控制台、全局变量、元标签以及静态文件等方式注入到您的应用程序中。

npm version npm downloads types License

Vite Nuxt

Awesome

使用样例

安装

pnpm add -D vite-plugin-version-mark
# 或者 yarn add -D vite-plugin-version-mark
# 或者 npm install -D vite-plugin-version-mark

使用

Vite

// vite.config.ts
import { defineConfig } from "vite";
import { vitePluginVersionMark } from "vite-plugin-version-mark";

export default defineConfig({
  plugins: [
    vitePluginVersionMark({
      // name: 'test-app',
      // version: '0.0.1',
      // command: 'git describe --tags',
      // outputFile: true,
      // ifGitSHA: true,
      ifShortSHA: true,
      ifMeta: true,
      ifLog: true,
      ifGlobal: true,
    }),
  ],
});

Nuxt3+

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    [
      "vite-plugin-version-mark/nuxt",
      {
        // name: 'test-app',
        // version: '0.0.1',
        // command: 'git describe --tags',
        // outputFile: true,
        // ifGitSHA: true,
        ifShortSHA: true,
        ifMeta: true,
        ifLog: true,
        ifGlobal: true,
      },
    ],
  ],
});

至此，你就在开始使用 vite-plugin-version-mark 啦! 🎉

🚀 v0.2.0 新功能：多命令支持！现在你可以执行多个 git 命令并使用自定义格式组合它们的结果。非常适合创建像 "main-abc1234" 或 "v1.0.0-main-abc1234" 这样的版本字符串。查看下方示例 ⬇️

配置

vite-plugin-version-mark 可以在 Console 中打印版本号，也可以在全局定义变量供您使用， 同时支持在 <meta> 标签中显示版本号。

属性描述类型默认值支持版本
name应用名string在 package.json 中定义的 name 属性0.0.1+
version应用版本string在 package.json 中定义的 version 属性0.0.1+
ifGitSHA使用 git commitSHA 作为版本号booleanfalse0.0.1+
ifShortSHA使用 git 的短 commitSHA 作为版本号booleanfalse0.0.1+
command提供自定义指令，以便自定义版本号的获取方式
新功能: 现在支持多命令！
例如使用 git tag 作为版本号: git describe --tags 或 { commands: ['git branch --show-current', 'git rev-parse --short HEAD'], format: '{0}-{1}' }		string | MultiCommandOptionsgit rev-parse --short HEAD0.0.8+
ifLog在控制台打印版本信息booleantrue0.0.1+
ifGlobal在 window 上定义变量 `__${APPNAME}_VERSION__`
对于 TypeScript 使用者, 请确保您在 env.d.ts 或者 vite-env.d.ts 文件中定义该变量，以便通过类型检查。		booleantrue0.0.4+
ifMeta在 <head> 中添加 <meta name="application-name" content="{APPNAME_VERSION}: {version}">booleantrue0.0.1+
ifExport在入口文件导出版本字段。这在您使用 vite 构建 library mode时或许会用到。
通过 import { {APPNAME}_VERSION} from <your_library_name>		booleanfalse0.0.11+
outputFile构建时根据版本生成一个静态文件，具体配置详见下方的 outputFile 配置项说明boolean/functionfalse0.1.1+

版本字段的取值优先级为: command > ifShortSHA > ifGitSHA > version

command 多命令支持 🎉 v0.2.0 新功能

从版本 0.2.0+ 开始，vite-plugin-version-mark 支持执行多个命令并组合它们的结果！这非常适合创建包含分支名和提交 SHA 的版本字符串。

基础多命令用法

// vite.config.ts
import { defineConfig } from "vite";
import { vitePluginVersionMark } from "vite-plugin-version-mark";

export default defineConfig({
  plugins: [
    vitePluginVersionMark({
      // 使用默认分隔符的简单多命令配置
      command: {
        commands: [
          "git rev-parse --abbrev-ref HEAD", // 获取分支名
          "git rev-parse --short HEAD", // 获取短提交 SHA
        ],
        // 输出: "main-abc1234"
      },
    }),
  ],
});

高级多命令配置

// vite.config.ts
export default defineConfig({
  plugins: [
    vitePluginVersionMark({
      command: {
        commands: [
          {
            alias: "branch",
            cmd: "git rev-parse --abbrev-ref HEAD",
            fallback: "unknown",
          },
          { alias: "sha", cmd: "git rev-parse --short HEAD", timeout: 5000 },
          {
            alias: "tag",
            cmd: "git describe --tags --abbrev=0",
            fallback: "v0.0.0",
          },
        ],
        format: "{tag}-{branch}-{sha}", // 自定义格式模板
        errorStrategy: "fallback", // 错误时使用回退值
        parallel: true, // 并行执行命令
        // 输出: "v1.0.0-main-abc1234"
      },
    }),
  ],
});

多命令选项

选项描述类型默认值
commands要执行的命令数组，可以是字符串或命令配置对象(string | CommandConfig)[]-
format带有 {alias} 占位符的模板字符串，用于格式化结果string-
separator未提供格式模板时的默认分隔符string"-"
errorStrategy处理命令失败的方式："strict"、"skip" 或 "fallback"string"skip"
parallel是否并行执行命令以提高性能booleantrue

错误处理策略

  • strict：任何命令失败都会抛出错误并停止构建
  • skip：跳过失败的命令，它们的结果在输出中为空
  • fallback：当命令失败时使用命令配置中指定的 fallback 值

命令配置

每个命令都可以配置额外的选项：

interface CommandConfig {
  alias: string; // 在格式模板中引用的别名
  cmd: string; // 实际执行的命令
  fallback?: string; // 命令失败时的回退值
  timeout?: number; // 命令超时时间（毫秒），默认 10000
}

outputFile 配置项说明

如需启用可设置为 true，会在相对构建目录（vite 默认为 dist，nuxt3 默认为 .output/public）下创建路径为 .well-known/version 的文件，内容为当前版本号。

也可以设置为一个函数，该函数接收版本号作为参数，并返回一个对象，以便自行定义生成的内容信息，例如：

// vite.config.ts
vitePluginVersionMark({
  // ...other options

  outputFile: (version) => ({
    path: 'custom/version.json',
    content: `{"version":"${version}"}`,
  })
}),

如此配置便可以生成一个名为 custom/version.json 的文件，内容为 {"version":"${当前版本号}"}。

其它

如何在您的 vite 插件中获取版本号？

// vite.config.ts

import { defineConfig } from "vite";
import type { Plugin } from "vite";
import { vitePluginVersionMark } from "vite-plugin-version-mark";

const yourPlugin: () => Plugin = () => ({
  name: "test-plugin",
  config(config) {
    // get version in vitePlugin if you open `ifGlobal`
    console.log(config.define);
  },
});

export default defineConfig({
  plugins: [
    vue(),
    vitePluginVersionMark({
      ifGlobal: true,
    }),
    yourPlugin(),
  ],
});

如何通过 提交SHA 来获取所属分支？

通过下方的 git 指令，可以列出所有包含指定 提交SHA 的分支。

git branch -r --contains <COMMIT_SHA>

Star History

Star History Chart

查看 CHANGELOG