HTML自定义元素无内置版本管理，版本实为类定义快照，须通过Git分支、构建注入、同步注册及全局变量控制，禁止HTML硬编码版本号。
HTML 自定义元素本身不支持版本管理，所谓“版本”只能靠外部手段控制——比如构建时注入、Git 分支约束、或运行时按类名/属性做兼容性判断。直接在 HTML 里写 <my-button version="2.0"> 或用 <meta name="version"> 标注，既不能触发行为变更，也无法被 JS 安全读取，纯属误导。
customElements.define() 注册时机决定“生效版本”
浏览器解析 HTML 时遇到 <ds-button>，会立刻按 HTMLUnknownElement 处理；如果此时 customElements.define('ds-button', ...) 还没执行，这个标签就永远失效——不会回滚、不会重试、也不会报错提示。
- 所有自定义元素注册必须收口到一个同步加载的入口文件（如
components/index.js），且不能放在import()动态分支里 - Vite/Webpack 构建时需检查：禁止把自定义元素类拆包到异步 chunk，否则首屏可能空白
- SSR 场景下必须加
if (typeof window !== 'undefined')包裹，否则 Node 环境直接崩 - 多个版本共存？靠类名区分：
class="ds-button-v2"+ 单独注册customElements.define('ds-button-v2', ...)，而不是复用同一标签名
attributeChangedCallback 不是版本开关，别当 if-else 用
attributeChangedCallback 只响应 observedAttributes 声明的属性变更，且只在 setAttribute() 调用后触发——它不感知构建时注入的常量、不读取 HTML 注释、也不响应 JS property 赋值（如 el.version = '3.1'）。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 想让组件响应版本逻辑？把版本号作为构建时变量注入全局对象，比如
window.__DS_VERSION = '3.1'，再在connectedCallback里判断 - 避免在
attributeChangedCallback里写if (name === 'version') { ... }——用户随时能改这个属性，不可信 - HTML 中写
<ds-button data-version="3.1">没问题，但得手动在connectedCallback里调this.getAttribute('data-version')读取，且不能依赖它做核心流程分支
Git 分支才是真正的“主版本+分支结构”载体
所谓“HTML 自定义元素版本管理”，实际是 Git 对整个 components/ 目录的管理：不同分支对应不同实现、不同 API、甚至不同注册方式。HTML 文件本身只是消费端，不是版本源头。
立即学习“前端免费学习笔记（深入）”；
-
main分支：只合入已验证的稳定版自定义元素，customElements.define('ds-button', ButtonV2) -
feature/button-v3分支：开发新版本，类名可能叫ButtonV3，注册为'ds-button-v3'，避免和线上冲突 - 发布前用
release/v3.0冻结代码，跑 E2E 测试确认所有<ds-button>和<ds-button-v3>行为无误 - 禁止在 HTML 里硬编码版本号路径，比如
<script src="button-v2.js">—— 改成构建时替换，或用模块导入统一管控
真正容易被忽略的是：自定义元素的“版本”本质是类定义的快照，不是字符串标识。你改了 ButtonV2 的 connectedCallback 逻辑，哪怕没动标签名，也已是新版本——Git 提交记录、构建产物哈希、CDN 缓存失效策略，这些才是它落地的锚点，不是 HTML 里的任意文本。
