customelements.define() 报错“元素名无效”必因命名不合规：须含至少一个ascii短横线、全小写、不含下划线/大写字母/冒号等非法字符，且不能与原生标签或保留前缀冲突。
customElements.define() 报 “The element name is not valid” 怎么快速定位
这几乎总是命名不合规导致的硬性拒绝，不是兼容性问题，也不是运行时异常——浏览器在 customElements.define() 执行瞬间就校验并抛出 DOMException，根本不会进入组件逻辑。
- 检查标签名是否含至少一个 ASCII 短横线（
-），mybutton、MyButton、my_button全部非法 - 确认全小写，
My-Button或MY-BUTTON都会失败 - 排除原生标签名：不能用
div、slot、template、html、body等；也不能用带保留前缀的名，如x--foo（双连字符）、html-test（以html开头） - 错误信息固定为：
DOMException: The element name is not valid，别指望try/catch捕获后还能补救——注册失败即组件未定义
为什么不能用下划线或驼峰命名自定义标签
HTML 规范明确要求自定义元素名必须含短横线（-），且只接受 ASCII 字符中的小写字母、数字、短横线组合。下划线（_）、点（.）、冒号（:）、大写字母全部被解析器直接拒绝。
-
my_button→ Safari 旧版本可能静默降级，Chrome/Firefox 直接报错 -
myButton或MyButton→ 含大写字母，触发DOMException -
qz:ss→ 冒号是 XML 命名空间语法，在 HTML 中无效；document.querySelector('qz:ss')查不到，CSS 里写qz\:ss也不生效 - 真正起“命名空间”作用的只有团队约定前缀，比如
shop-button、dash-modal，但这是协作规范，不是语法强制
注册时机不对会导致标签“存在但不工作”
即使名字合法、类继承正确，如果 customElements.define() 执行晚于对应标签在 DOM 中的解析，该节点就会卡在 HTMLUnknownElement 状态，生命周期方法（如 connectedCallback）完全不触发。
- 常见场景：脚本放在
底部，但<my-button></my-button>已写在上方 - 解决方案：把注册逻辑提前到
中的<script></script>，或包裹在DOMContentLoaded事件里 - 已存在的未升级节点，必须手动调用
customElements.upgrade(document.querySelector('my-button'))，否则不会激活 - 不要在
connectedCallback里靠this.localName做前缀分支（如if (name.includes('shop-'))），这破坏封装，也使组件无法跨项目复用
class/id 和自定义标签名是两回事，别混用
my-button 是一个全局注册的 DOM 类型，而 class="my-button" 只是一个样式标识符，语义和作用域完全不同。
- 写成
<div class="my-button"> → 不会触发任何组件逻辑，它就是一个普通 <code>div - 正确写法是
<my-button></my-button>，哪怕你同时加了class="btn-primary"，那也只是用于样式，和组件功能无关 - 查询组件实例要用
document.querySelector('my-button')，而不是.my-button（除非你真给它设了那个 class） - 注册成功后，
customElements.get('my-button')能取到构造函数；但customElements.get('button')永远返回undefined，因为原生标签不走这套机制
命名本身看似简单，但浏览器的校验是即时且严格的。最容易被忽略的不是“怎么起名”，而是“什么时候注册”和“怎么查实例”——这两个点一旦出错，调试时看不到报错，却死活不执行回调，比语法错误更难排查。
