Git仓库结构必须按组件路径组织，如src/components/header/下包含HTML/CSS/JS及assets，确保构建时资源完整；提交信息需含组件名与变更类型；构建时通过define或DefinePlugin注入版本号，禁止运行时读取；分支策略应绑定组件生命周期而非页面层级。
Git 仓库结构必须按组件路径组织，不能只存 HTML 文件
HTML 模板或组件不是孤立文件，它们依赖 CSS、JS、图标甚至字体路径。如果只把 header.html 单独提交，而漏掉 header.css 或 assets/logo.svg，构建时就会报错或渲染异常。Git 必须跟踪整个组件单元。
- 固定路径如
src/components/header/，内含index.html、style.css、script.js、assets/ - 禁止在组件目录外硬编码引用资源，比如
<img src="/images/logo.png">——路径应为相对的<img src="./assets/logo.svg"> -
git status运行后，所有相关文件都应显示为 tracked 状态；若出现 untracked，说明路径没纳入管理
Vite / Webpack 构建时注入版本号，别用 JS 运行时读取
用户看到的 “v2.4.1” 必须来自构建上下文，而不是页面加载后再去请求 /version.json 或解析 <meta name="version">。后者在生产环境大概率失败：文件可能被 CDN 缓存、路径错、权限拒、甚至根本没部署。
- Vite 项目中，在
vite.config.ts里用define注入：__COMPONENT_VER: JSON.stringify(pkg.version) - HTML 中写成：
<footer>© 2026 <span id="ver">%__COMPONENT_VER%</span></footer>，构建工具会替换占位符 - Webpack 可用
DefinePlugin+html-webpack-plugin的templateParameters实现类似效果 - 绝对不要在 JS 里写
document.querySelector('meta[name="version"]').getAttribute('content')——它不可靠，且无法覆盖 SSR 场景
提交信息必须带组件名和变更类型，否则合并时无法定位问题
多人协作改同一套模板时，模糊的提交如 “update files” 或 “fix bug” 会让代码审查和回滚变成猜谜。Git 不会自动告诉你这段 HTML 是哪个组件、为什么改、改了哪几处。
- 正确格式：
feat(navbar): 支持深色模式切换按钮、refactor(footer): 提取版权年份为变量 - 改完
src/components/footer/index.html后，运行git diff origin/main -- src/components/footer/确认只动了预期文件 - 禁止
git add .全量提交——容易误提dist/、node_modules/或本地调试用的临时 HTML - 如果组件含 JS 逻辑，确保
script.js和调用它的 HTML 同步提交；否则 Git 看似通过，页面实际报Uncaught ReferenceError
分支策略要绑定组件生命周期，而非页面层级
HTML 组件库的分支不该按“首页”“关于我们”这种页面划分，而应按组件本身的演进节奏来切。一个 button 组件的重构，可能影响十几个页面，但它本身就是一个独立交付单元。
立即学习“前端免费学习笔记（深入）”；
- 主干用
main，只合入已测试通过的组件变更 - 新功能用
feature/button-v2，包含该组件全部文件（HTML/CSS/JS/测试用例） - 紧急修复走
hotfix/modal-close，仅修改src/components/modal/下文件，不碰其他组件 - 发布前建
release/v3.1.0分支做最终校验，此时可加构建注释：<!-- BUILD: v3.1.0 -->，但仅作人工识别，不参与逻辑
真正难的不是写清楚版本号，而是让每个 HTML 片段背后都有一条可追溯、可隔离、可验证的变更链——它藏在路径设计里，卡在提交规范里，也压在构建配置里。少一个环节，就等于把组件扔进黑盒。
