customElements.define必须在HTML解析前执行，否则已存在的自定义标签将永久作为HTMLUnknownElement不升级；需内联注册或用type="module" defer确保时机，CMS场景下须手动调用customElements.upgrade()。
customElements.define 必须在 HTML 解析前执行
自定义元素注册晚了，页面里已存在的 <my-button> 标签永远不会升级——它们始终是 HTMLUnknownElement，connectedCallback 也不会触发。这不是 bug，是浏览器解析机制决定的。
常见错误现象：组件 JS 已加载，但页面上所有自定义标签都无样式、无行为，检查发现 customElements.get('my-button') 返回构造函数，而节点的 constructor 却仍是 HTMLUnknownElement。
- 正确做法：把
customElements.define('my-button', MyButton)放在<script>标签内联执行，或用type="module" defer确保早于 HTML 解析完成 - 若无法控制 HTML 输出顺序（如 CMS 渲染），必须手动升级：遍历匹配节点并调用
customElements.upgrade(node) - 动态插入含自定义标签的 HTML 字符串（如
el.innerHTML = '<my-card></my-card>'）后，必须立即对插入的节点调用customElements.upgrade()，否则生命周期静默
connectedCallback 中必须防重复初始化
connectedCallback 不是“构造函数”，它会在元素每次被插入活跃 DOM 树时触发——包括 Vue/React 列表重渲染、display: none 切回、appendChild 多次调用等场景。把它当初始化入口，很容易导致 Shadow DOM 多次 attach、事件重复绑定、定时器叠加、fetch 请求发多次。
典型错误：在 connectedCallback 里直接写 this.attachShadow({ mode: 'open' }) 或 this.addEventListener('click', handler)，结果用户点一次按钮，绑了三次监听器。
立即学习“前端免费学习笔记（深入）”；
- 加守卫：用
if (this._initialized) return;+this._initialized = true控制仅执行一次 - Shadow DOM 创建也应加判断：
if (!this.shadowRoot) this.attachShadow({ mode: 'open' }) - 事件监听器应在
disconnectedCallback中对应清理，避免内存泄漏
用 data- 属性替代 class/id 定位自定义组件内部节点
现代框架（Vue、React）、CSS-in-JS 或 CSS Modules 会让 class 名动态哈希（如 Button__root___1x2y3），ID 更难保证唯一和可预测。依赖它们查 DOM，极易在构建后失效。
常见错误现象：document.querySelector('.btn-primary') 在本地开发正常，上线后返回 null；或 E2E 测试脚本频繁因 class 名变更而中断。
- 写 HTML 时主动加语义化
data-属性：<input data-role="search-input"> - JS 中查：
document.querySelector('[data-role="search-input"]')，稳定且不干扰样式 - 避免带序号的
data-test-id="item-1"，改用行为语义：data-action="submit"或data-section="sidebar" - 批量操作时，用
const cards = document.querySelectorAll('my-card[data-status="active"]')，再forEach，比循环里反复querySelector安全得多
动态插入后 upgrade 要分片，别一口气干完
customElements.upgrade(node) 是同步操作。如果一次要升级上千个新插入的自定义节点，主线程会卡死，页面冻结，用户感知明显卡顿。
这不是性能瓶颈本身，而是调度方式问题——浏览器没机会做渲染帧更新，也没法响应用户输入。
- 不要对整个容器反复调用
upgrade，只对新增节点及其子树调用 - 大量节点时，用
requestIdleCallback分片处理，例如每帧最多处理 50 个：processBatch(50); requestIdleCallback(loop, { timeout: 1000 }); - IE 不支持
requestIdleCallback，fallback 到setTimeout，但至少设16毫秒，别用0 - MutationObserver 可监听新增节点，只对新增部分升级，避免全量扫描
真正容易被忽略的是：自定义元素的性能问题几乎从不来自 define，而来自挂载阶段的失控初始化和升级时机错配。DOM 查询只是表象，根子在生命周期管理是否收敛。
