17370845950

HTML5无内置版本号机制，需通过构建流程在静态资源URL中嵌入版本标识（如哈希值）以解决缓存问题；硬编码或meta标签写死版本号无效，真正生效的是资源路径变更；推荐Git Tag+CI自动注入版本至文件名与构建元信息。

HTML5 源代码本身不内置版本号机制，所谓“加版本号”实际是通过构建流程、资源引用或元信息手动注入，目的是解决缓存失效、CDN 更新、灰度发布等实际问题。

用 标签写死版本号？不推荐

有人在 里加：

这看似简单，但浏览器不解析、CDN 不识别、前端监控难采集，纯属自嗨。它既不影响资源加载，也无法触发缓存刷新，唯一作用可能是给人工查源码时看一眼——而真正需要版本信息的场景（比如排查线上 bug）根本来不及翻源码。

真正起效：在静态资源 URL 中嵌入版本标识

浏览器和 CDN 缓存依赖 URL 字符串是否变化。只要 URL 改了，就强制重新拉取。关键不是“写在哪”，而是“让资源路径带上可变标识”。常见做法：

• script.js?v=2.3.1 —— query 参数方式，简单但部分 CDN 默认忽略 query 缓存（需额外配置）
• script.2.3.1.js —— 文件名内嵌，兼容性最好，但需构建工具重命名输出
• script.a1b2c3.js —— 哈希值后缀（如 Webpack 的 [contenthash]），最可靠，文件内容变则 hash 变，天然防缓存错乱

注意： 中的 _v 是为了绕开某些代理对无下划线 v 参数的过滤，不是玄学，是真实踩过的坑。

构建时自动注入：Webpack/Vite/Nuxt 等怎么配

硬编码版本号很快会过期。应该从 package.json 的 version 字段或 Git 提交哈希中读取，并注入到 HTML 模板中。例如 Vite：

export default defineConfig({
  define: {
    __APP_VERSION__: JSON.stringify(pkg.version),
  },
})

然后在 index.html 中：

但这仍只是元信息；真正要生效，还得配合上面说的资源 URL 哈希化。否则，__APP_VERSION__ 再准，main.js 还是被缓存着。

Git Tag + CI 自动打标才是可持续方案

靠人手改 package.json 版本容易漏、易冲突。规范做法是：

• 功能开发完，合并到 main 后，CI 流水线检测最新 Git tag（如 v2.3.1）
• 用 git describe --tags --always 生成类似 v2.3.1-5-ga1b2c3d 的构建标识
• 该标识同时用于：文件名哈希前缀、环境变量注入、Sentry source map 关联、日志上报字段

别只盯着 HTML 文件本身加版本号——HTML 是入口，但 JS/CSS/图片才是缓存主力。没动它们的 URL，HTML 里写满版本也没用。