customElements.define() 报错最常见原因是标签名不合法（须含连字符且全小写）或类未继承 HTMLElement/constructor 中未调用 super()；connectedCallback 中应执行 DOM 相关操作，避免提前读取属性或重复 attachShadow；Shadow DOM 需通过 :host 和 CSS 自定义属性实现可控样式隔离；Declarative Shadow DOM 有兼容性与构建配置限制。
customElements.define() 报错：Failed to execute 'define' on 'CustomElementRegistry'
最常见原因是标签名不合法或类定义不合规。浏览器强制要求自定义标签必须含连字符，且不能以连字符开头或结尾。my-button 合法，myButton、-my-button、my-button- 全部会触发该错误。
另一个高频原因是类没继承 HTMLElement，或在 constructor 中漏掉 super()。这会导致原型链断裂，注册直接失败。
- 检查标签名是否全小写 + 至少一个连字符（如
data-table、search-facet） - 确认类声明为
class MyButton extends HTMLElement -
constructor()第一行必须是super()，否则后续所有生命周期方法都不会被调用 - 避免在
constructor里读取this.innerHTML或调用this.querySelector——此时 DOM 尚未挂载
connectedCallback 里该放什么，不该放什么
connectedCallback 是元素真正插入文档后的第一个钩子，所有依赖 DOM 存在的逻辑必须放在这里，而不是 constructor。
常见误用是把事件绑定、属性读取、首次渲染补全提前到 constructor，结果 this.shadowRoot 为 null 或 this.getAttribute('size') 返回 null。
立即学习“前端免费学习笔记（深入）”；
- ✅ 在
connectedCallback中调用this.attachShadow({ mode: 'open' })（如果还没做） - ✅ 绑定事件：
this.addEventListener('click', ...) - ✅ 读取初始属性：
this.getAttribute('disabled')并同步到 shadow 内部 - ✅ 触发首次渲染（尤其当组件依赖 slot 或外部传入内容时）
- ❌ 不要在
connectedCallback里重复 attachShadow（已存在会报错） - ❌ 避免在此处启动长期运行的定时器，除非你同时在
disconnectedCallback清理
Shadow DOM 样式隔离但不等于“自动可定制”
很多人以为把 <style> 塞进 shadow root 就万事大吉，结果发现用户没法改背景色，或者外部 CSS 意外穿透进来。
关键不在“有没有样式”，而在“样式怎么暴露、怎么接收、怎么隔离”。<host> 和 CSS 自定义属性是控制权交接点。
- 样式必须内联注入：
<link rel="stylesheet">在 shadow root 中无效 - 用
:host控制组件自身状态样式，例如:host([disabled]) { opacity: 0.5; } - 暴露
--my-button-bg这类自定义属性，让用户通过style="--my-button-bg: red;"覆盖 - 慎用
::slotted或/deep/，它们破坏封装性，且 Safari 对::slotted(.icon)的匹配行为不稳定 - 注意：CSS containment 不影响 shadow root，它只作用于 light DOM 容器
服务端直出 Shadow DOM 的坑：Declarative Shadow DOM 不是万能钥匙
用 <template shadowroot="open"> 确实能跳过 JS hydration、消除 FOUC，但它的限制比想象中多。
最常踩的坑是模板里写了 <script> 或忘了配置构建工具保留 template[shadowroot] 属性——Webpack/Vite 默认会剥离它。
- 仅支持
shadowroot="open"，"closed"仍需 JS 创建 - 模板内禁止
<script>，事件绑定、数据请求等逻辑必须由宿主元素的 JS 补充 - Vite 用户需加
vite-plugin-html插件并配置includeAssetsTags: true - Webpack 用户要配
html-loader并启用attributes选项保留shadowroot - Safari 17.4+ 才完全支持，旧版 Safari 会忽略该 template，降级为普通 light DOM
