HTML模板不是独立发版单元，必须绑定项目Git路径，通过提交历史体现变更；禁止单独打标签或改名，需固定路径、关联资源一并提交，构建时注入可信版本号，静态资源URL须带内容哈希。
HTML模板不是独立发版单元，必须绑定项目Git路径
HTML模板（比如 header.html、card.tpl 或 Vue 的 Card.vue）本身没有版本号概念。所谓“组件版本控制”，本质是它在项目仓库中的文件路径被 Git 跟踪，并通过提交历史体现变更。把它单独拎出来打个 v2.0.0 标签、上传到 CDN 或改名成 header-v2.html，都会破坏引用一致性，导致构建失败或运行时 404。
常见错误现象：include("header-v2.html") 在 PHP 模板里硬编码路径，但没人记得删掉旧的 header-v1.html；或者 Vite 项目里用 import Header from "./Header.v2.vue"，结果 TypeScript 类型检查报错找不到模块。
- 模板必须放在固定路径下，如
src/components/Header.vue或templates/partials/footer.html，且该路径被构建工具识别为依赖入口 - 所有关联资源（CSS、JS、SVG、图片）必须和模板文件一起提交，
git status应显示它们都在暂存区 - 禁止用 CMS 导出后直接覆盖本地文件——这会丢失 Git 历史；应把 CMS 输出内容粘贴进已跟踪的模板文件，再 commit
构建时注入版本标识，而不是运行时 JS 拼接
用户看到的“当前组件版本”必须来自构建上下文，不能靠 document.querySelector('[data-component="header"]').dataset.version 这种运行时读取逻辑。后者依赖 DOM 已加载、JS 已执行，且无法保证数据来源可信。
正确做法是在构建阶段把版本固化进 HTML 输出。例如：
立即学习“前端免费学习笔记（深入）”；
- Vite：在
vite.config.ts中配置define: { __HEADER_VER__: JSON.stringify('v1.3.2') }，模板中写<div data-version="%__HEADER_VER__%">，Vite 会自动替换 - Webpack + HtmlWebpackPlugin：用
html-webpack-plugin-options.templateParameters注入变量，模板中写<!-- HEADER_VERSION: --> - 服务端渲染（如 Express + EJS）：启动时读取
package.json的version字段，传入模板上下文
绝对不要：fetch("/version.json").then(...) 渲染版本号——这个请求可能失败、缓存、跨域，且首屏不可见。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
提交信息必须明确组件名与变更类型
Git 提交不是“保存快照”，而是回答“谁改了什么、为什么改”。对 HTML 模板而言，模糊的 git commit -m "update" 或 "fix bug" 会让后续排查变得困难。
每次修改模板前，先确认变更影响范围：
- 是否只改了结构？→ 提交信息用
feat(header): 支持 dark-mode 属性 - 是否调整了 class 名或移除了内联样式？→
refactor(header): 移除 style 属性，统一由 CSS-in-JS 控制 - 是否修复了 SSR 下缺失的属性？→
fix(header): 补全 data-testid，确保测试可定位 - 涉及多个模板联动修改（如
header和nav同时加无障碍属性），应建临时分支feature/a11y-sweep，合并前 rebase 到最新main
禁止 git add . 全量提交——容易误带 dist/、node_modules/ 或未清理的调试注释。
静态资源 URL 必须带哈希，不能只改 HTML 里的 meta 版本
用户看到的版本号只是表象，真正起作用的是资源 URL 是否变化。如果 header.html 里写了 <meta name="version" content="v2.1.0">，但 header.js 的 URL 还是 /js/header.js，那浏览器永远用旧 JS，版本号再准也没用。
构建工具必须生成带内容哈希的资源路径：
- Webpack：启用
[contenthash]，输出header.8a3f2d.js，HtmlWebpackPlugin 自动重写<script src> - Vite：默认开启
build.rollupOptions.output.assetFileNames哈希，CSS/JS/字体均带 hash - 纯静态模板（如 Nunjucks）：读取构建产物的
manifest.json，用{% set js_url = manifest['header.js'] %}插入真实路径
最容易被忽略的一点：CSS 文件里的 url(./logo.svg) 也受构建哈希影响。如果没配好 public/ 或 assets/ 处理规则，logo.svg 可能没进哈希队列，导致样式失效。
