Skip to content

版本与构建追踪 ​

发布版本由项目根目录 package.json 的 version 管理。每次执行 build,模板自动生成独立的构建编号、构建时间和 Git 信息,不修改任何源码或版本文件。

日常使用 ​

bash
pnpm build

打包完成后:

  • 终端显示发布版本和构建编号;
  • 浏览器加载应用时,控制台以版本徽标和对齐的明细显示一次构建信息,生产环境也保留;
  • dist/version.json 包含相同的构建信息,与静态资源一起部署;
  • 错误诊断记录中的 version、buildId 与本次产物一致。

例如:

json
{
  "version": "1.2.3",
  "buildId": "20261111T073000000Z-a84c921bf012-1b2c3d4e",
  "gitCommit": "a84c921bf0123456789012345678901234567890",
  "gitDirty": false,
  "builtAt": "2026-11-11T07:30:00.000Z",
  "mode": "production"
}

builtAt 为 UTC 构建时间,mode 为 Vite 构建模式,两者都不代表实际部署时间或部署环境。同一份产物可在多个环境部署,回滚也使用已归档的原产物。

控制台的 Built at 会将该时间转换为浏览器所在系统的本地时区,并显示时区偏移。例如上海时区显示 2026-11-11 15:30:00 GMT+8;version.json 和展开的原始数据仍保留 UTC 时间。

发布版本与构建编号 ​

日常修改由 Git 提交记录,每次打包自动生成新的 buildId。编号由 UTC 时间、Git 提交前 12 位和随机后缀组成,包含未提交修改时追加 dirty 标记;同一提交重复打包也会生成不同编号。

准备正式发布时再修改 package.json 的 version。也可以在业务项目根目录执行:

bash
npm version patch --no-git-tag-version

该命令将 1.2.3 升级到 1.2.4,不自动创建 Git 提交和标签。minor、major 分别用于升级次版本和主版本。版本文件仍需按项目流程提交;源仓库中应修改 apps/template/package.json,不要误改 workspace 根包或模板发布包的版本。

模板发布包 @kevairy/template 的版本与生成后的业务应用版本独立。应用版本不再读取 .env 中的 VITE_VERSION;已有配置应迁移到项目的 package.json。

构建编号不参与 LocalStorage 存储键生成,不会因为重复打包而触发存储版本迁移。应用发布版本仍沿用现有的存储版本机制。

Git 与 CI ​

默认读取构建工作区的 Git 提交和状态,未跟踪文件也视为未提交修改。没有 Git 或 .git 时仍可构建,gitCommit、gitDirty 为 null,自动编号中使用 nogit。只有 gitDirty: false 才代表已确认工作区干净;null 表示未知。

CI 可以通过进程环境变量显式注入:

变量用途
VITE_BUILD_ID覆盖自动编号,CI 应保证每次构建唯一,例如流水线编号加重试序号
BUILD_GIT_COMMIT指定源代码提交,适用于源码归档或构建容器内没有 .git 的情况
BUILD_GIT_DIRTY显式指定 true 或 false;其他非空值会导致构建失败
bash
VITE_BUILD_ID=pipeline-123-attempt-1 \
BUILD_GIT_COMMIT=a84c921bf0123456789012345678901234567890 \
BUILD_GIT_DIRTY=false \
pnpm build

只注入 BUILD_GIT_COMMIT 时,工作区状态标为未知,不使用构建机目录的状态推断该提交是否干净。Git 信息在构建时采集,部署服务器不需要安装 Git。

构建信息是公开数据,仅包含上述字段,不收集仓库地址、用户信息或提交内容。不要把凭证放入自定义构建编号。

部署与缓存 ​

version.json 位于部署基础路径下。例如 VITE_BASE_URL=/admin/ 时,访问 /admin/version.json。

浏览器启动输出代表当前页面已加载的产物;访问服务器的 version.json 代表服务器当前提供的产物。两者可能因为旧页面、CDN 缓存或分批发布而不同。启动信息直接来自 JS 内嵌常量,不通过请求服务器版本替换当前页面的版本。

部署时应完整更新同一批产物,并对 version.json 配置 Cache-Control: no-store,避免运维查询命中旧缓存。Nginx 示例(子路径部署时相应调整匹配路径):

nginx
location = /version.json {
    add_header Cache-Control "no-store" always;
}

按构建编号归档发布包,并保留相应 Git 提交与部署记录,即可支持排障和回滚。模板不自动创建 Git 标签、发布包归档或部署记录。