customElements.define() 是浏览器运行时 API，非编译器处理；构建工具仅确保类定义正确执行、避免模板误解析、适配 SSR 水合与 Shadow DOM 渲染。
编译器本身不直接处理 customElement 配置——它属于运行时注册逻辑，由浏览器原生 API（customElements.define()）执行。所谓“编译器处理”，实际是指构建工具（如 Vite、Webpack、Angular CLI）或框架（如 Angular、Vue）在打包/转译阶段如何识别、包裹、注入或适配自定义元素的声明与使用，从而避免渲染冲突。
customElement 配置的本质是运行时注册
Web Components 的核心机制依赖浏览器对 customElements.define('my-button', MyButton) 的调用。这个过程发生在 JavaScript 执行阶段，不是编译期行为。构建工具只负责：
- 确保类定义（
MyButton extends HTMLElement）被正确导入并执行； - 避免将自定义元素名误判为未知 HTML 标签而报错（例如 Vue 模板中写
- 在 SSR 场景下跳过 Shadow DOM 渲染或延迟 hydrate，防止服务端与客户端 DOM 结构不一致。
常见框架中 customElement 的适配要点
不同框架对自定义元素的支持策略不同，错误配置易引发渲染冲突：
-
Vue：默认把所有小写连字符标签（如
app.config.compilerOptions.isCustomElement中显式声明：
app.config.compilerOptions.isCustomElement = tag => tag.startsWith('my-'); -
React：不内置 Web Components 支持，需手动处理属性传递（如
className→class）、事件监听（onMyEvent→addEventListener('myevent')）。推荐用react-web-component等封装库桥接。 -
Angular：通过
NgElementConstructor和createCustomElement()将 Angular 组件包装为 Custom Element。关键点是：必须在模块中导入BrowserModule并调用defineCustomElements()，否则组件无法注册；同时禁用 Angular 的变更检测优化（如ChangeDetectionStrategy.OnPush）可能影响 slot 内容更新。
渲染冲突的典型场景与修复
冲突多源于 slot 分发、属性同步、生命周期错位：
-
Slot 内容只出现在第一个位置：这是 Web Components 规范行为（内容被移动而非复制），不是 bug。若需多处复用同一图标，不能靠多个同名
@Input()或属性传入 SVG 字符串/HTML 字符串，再由组件内部innerHTML插入（注意 XSS 风险）或用cloneNode(true)手动克隆节点。 -
SSR 后水合失败（Hydration Error）：服务端渲染时 Shadow DOM 不生效，生成的是扁平 HTML；客户端 hydrate 时却试图挂载 Shadow DOM，结构不匹配。解法是：服务端跳过
attachShadow，或使用DeferHydration（Angular Elements）/client:only（Svelte）等指令控制 hydrate 时机。 -
样式泄漏或隔离失效：自定义元素若未启用 Shadow DOM，其样式会污染全局；若启用了但外部 CSS 仍能穿透（如通过
::part或::theme），需检查是否遗漏mode: 'open'或未正确导出 CSS 部分。
