Vue 3 项目需通过生成 version.json、注入全局版本变量、资源名加时间戳及运行时检测实现版本控制与缓存更新：构建时生成含时间戳的 version.json；Vite define 注入 VERSION 并挂载为 window.__APP_VERSION__；资源文件名添加时间戳增强兼容性；运行时定时 fetch version.json 比对并提示刷新。
Vue 3 项目（尤其是基于 Vite 构建的）要实现版本号自动注入与打包时间戳，核心目标有两个：一是让每次构建产出唯一可识别的版本标识；二是确保浏览器能感知更新、避免旧缓存干扰新资源。这不是单纯改个文件名，而是需前后端协同、构建与运行时配合的一整套机制。
生成 version.json 版本文件（构建时写入）
在打包阶段自动生成一个包含版本信息的静态文件（如 public/version.json），是最轻量且通用的做法。推荐用时间戳作为版本号，保证每次构建唯一：
- 新建脚本 scripts/build-version.js，内容如下：
const fs = require('fs');<br>const path = require('path');<br>const version = new Date().getTime().toString();<br>const versionJson = {<br> version,<br> updateTime: new Date().toLocaleString('zh-CN')<br>};<br>const versionPath = path.resolve(__dirname, '../public/version.json');<br>fs.writeFileSync(versionPath, JSON.stringify(versionJson, null, 2), 'utf-8');<br>console.log(`✅ 版本文件已生成，当前版本：${version}`);
- 在 package.json 的构建命令中前置执行它，例如：
"build": "node scripts/build-version.js && vite build" - 确保 public/version.json 被部署到服务器，并禁止被 CDN 或 Nginx 缓存（关键！否则检测失效）
在 HTML 中动态注入版本号（运行时可用）
仅靠 version.json 不够——页面首次加载时，JS 还没执行，无法主动拉取。更稳妥的方式是把版本号直接挂载为全局变量，供后续逻辑使用：
- 修改 index.html，在
<head>中添加占位 script 标签：<script id="version-script"></script> - 在 main.ts 入口顶部加入初始化逻辑（生产环境生效）：
if (import.meta.env.PROD) {<br> const version = __VERSION__ || new Date().getTime().toString();<br> (window as any).__APP_VERSION__ = version;<br>}
- 再通过 Vite 的
define或html.inject插件，在构建时将实际版本号注入__VERSION__。例如在 vite.config.ts 中配置：define: { '__VERSION__': JSON.stringify(new Date().getTime()) }
配置资源文件名带时间戳（强制刷新缓存）
虽然 Vite 默认使用 contentHash，但部分老旧环境（如微信内置浏览器）仍可能因 index.html 缓存导致 JS/CSS 请求旧地址。可在构建输出中追加时间戳参数增强兼容性：
立即学习“前端免费学习笔记（深入）”；
- 在 vite.config.ts 的
build.rollupOptions.output中调整：
build: {<br> rollupOptions: {<br> output: {<br> entryFileNames: `assets/[name].${Date.now()}.js`,<br> chunkFileNames: `assets/[name].${Date.now()}.js`,<br> assetFileNames: `assets/[name].${Date.now()}.[ext]`<br> }<br> }<br>}
- 注意：此方式会让所有资源 hash 失效，不适用于长期缓存策略；建议仅在灰度或兼容性兜底场景启用
- 更推荐做法是配合 Nginx 配置禁用 index.html 缓存：
location = /index.html { add_header Cache-Control "no-cache"; }
运行时检测并提示更新（用户侧感知）
有了版本源，还需在前端主动比对。常见做法是在路由守卫或定时轮询中请求 version.json：
- 创建 src/utils/versionCheck.ts，封装检查逻辑：
export async function checkVersion() {<br> try {<br> const res = await fetch('/version.json?_t=' + Date.now(), { cache: 'no-store' });<br> const { version } = await res.json();<br> const local = localStorage.getItem('__APP_VERSION__');<br> if (local && local !== version) {<br> if (confirm('检测到新版本，是否立即刷新？')) location.reload();<br> localStorage.setItem('__APP_VERSION__', version);<br> }<br> } catch (e) {<br> console.warn('版本检查失败', e);<br> }<br>}
- 在 main.ts 或路由 beforeEach 中调用，例如每 5 分钟检查一次
- 确保 fetch 请求带
?_t=xxx和cache: 'no-store'，绕过浏览器缓存
