版本号必须在构建阶段从package.json或Git哈希注入HTML，不可运行时JS读取；HTML注释需置于顶部且用JSON格式；静态资源URL应加?v=哈希参数；组件版本即其Git提交快照。
构建时注入版本号，别碰运行时 JS 拼接
页面上显示的 v1.2.3 必须在 HTML 构建阶段就固化，不能靠 JS 在浏览器里读 package.json 或发请求取 /version.json ——生产环境根本没这些文件，请求还可能 404、被 CDN 缓存、路径错，最终渲染出 undefined。
真正可信的来源只有两个：package.json 的 version 字段，或 Git commit hash（比如 git rev-parse --short HEAD）。构建工具必须从这里读，再塞进 HTML 模板。
- Vite：用
define注入，如__APP_VERSION__: JSON.stringify(pkg.version)，然后在index.html里写%__APP_VERSION__%占位符 - Webpack + html-webpack-plugin：通过
templateParameters传入版本变量，模板中用 - Node.js SSR：模板直插
{{ VERSION }}，确保和当前部署包完全一致
HTML 注释里存元信息，位置和格式都不能错
想在源码里留个可读又不影响渲染的版本记录？用 <!-- build: {"version":"2.1.3","timestamp":"2024-05-12T08:32:15Z"} --> 这种 JSON 格式注释，但必须放在 最顶部、 标签正后方。放错位置（比如 底部）会导致构建工具或静态分析器漏读。
JS 脚本读它时也容易翻车：CSS 选择器查不到注释节点；document.querySelector('comment') 是无效的；必须遍历 document.documentElement.childNodes，逐个判断 nodeType === 8，再用正则匹配前缀并 JSON.parse ——而且得套 try/catch，因为人工改过或构建失败会让 JSON 不合法。
立即学习“前端免费学习笔记（深入）”；
静态资源 URL 加版本参数，不是改文件名
解决缓存问题的核心是让 URL 变——但别盲目重命名文件（如 app.a1b2c3.js），尤其当 HTML 是后端模板生成、无法自动替换路径时。更稳妥的是加查询参数：app.js?v=a1b2c3。
不同工具处理方式差异大：
- Gulp：改
gulp-rev源码，把第 133 行manifest[originalFile] = revisionedFile改成manifest[originalFile] = originalFile + '?v=' + file.revHash - Maven：用
maven-replacer-plugin在prepare-package阶段正则替换 HTML 中的.js和.css路径 - Python 脚本：用
re.sub匹配<link.> 和 <code><script.>，插入 <code>?v=+ 时间戳或哈希
注意：所有方案都必须确保 HTML 文件本身参与构建流程，否则替换会失效。
组件级版本控制，本质是 Git 路径管理
所谓“HTML 组件”（比如 header.html 或 Web Component）没有独立版本号概念。它的版本就是 Git 提交历史里那个文件的变更快照。硬要在里面写 <meta name="version" content="1.2.0"> 没意义——既不触发缓存更新，也无法被自动化工具读取校验。
可靠做法只有两条：
- 组件源码必须放在项目仓库内固定路径（如
src/components/），且每次修改都走完整提交流程，提交信息明确标注组件名和变更类型，例如feat(card): 支持暗色模式 class - 构建时从同一 Git 上下文注入版本标识（如 commit hash），而不是运行时 JS 去解析 HTML 注释或 DOM 文本——后者不可靠，且无法覆盖服务端渲染场景
最容易被忽略的一点：组件若含 JS/CSS，必须连同 HTML 一起提交；只改 HTML 而漏提依赖文件，构建会失败，版本也就断链了。
