customelements.define()必须同步执行，不能接收promise或异步工厂函数；未定义标签会被当作htmlunknownelement处理，需先占位再调用customelements.upgrade()激活。
HTML 自定义元素本身不支持异步加载——customElements.define() 必须同步注册类，浏览器遇到未定义的 <x-button></x-button> 标签时，只会把它当 HTMLUnknownElement 处理，不触发任何生命周期，也不渲染 Shadow DOM。所谓“异步加载”，本质是控制注册时机 + 手动升级已存在节点。
customElements.define() 为什么不能接 Promise
常见错误写法：customElements.define('x-chart', () => import('./chart.js').then(m => m.XChart))，会直接报 TypeError: Class constructor XChart cannot be invoked without 'new'。因为 customElements.define() 第二个参数必须是**同步返回的 class 构造函数**，不是工厂函数，更不是 Promise。
- 动态
import()返回的是 Promise，不能塞进define() - 即使你用
await包裹，模块顶层执行顺序仍不可控：HTML 已解析完，但define()还没跑 -
script标签没加type="module"时，import()直接报Failed to resolve module specifier
先占位、后 upgrade 是唯一可靠路径
核心逻辑是让自定义标签提前出现在 DOM 中（SSR 输出或静态 HTML 写死），等模块加载完成、define() 执行后，再调用 customElements.upgrade() 激活已有节点。
- 必须先调
customElements.whenDefined('x-chart')等待注册就绪，否则upgrade()无效 -
customElements.upgrade(node)只对当前已挂载的节点生效；新插入的节点会自动升级（前提是已定义） - Shadow DOM 内部的查询需手动遍历，
document.querySelectorAll('x-chart')不会命中 Shadow DOM 里的实例 - SSR 场景下容易出现 FOUC（Flash of Unstyled Content），因为样式可能晚于 upgrade 执行
示例代码：
async function loadAndDefineChart() {
const mod = await import('./chart.js');
customElements.define('x-chart', mod.XChart);
document.querySelectorAll('x-chart').forEach(el => customElements.upgrade(el));
}
loadAndDefineChart();
动态 import 的构建注意事项
Webpack/Vite 对 import() 的处理不是“写了就能拆包”，路径必须是静态字符串，否则无法生成独立 chunk。
- ✅ 正确：
import('./chart.js')、import('./components/x-chart.js') - ❌ 错误：
import(`./${name}.js`)、import('./' + path)—— 打包器无法静态分析，降级为全量打包 - 构建产物中，
import()加载的模块若含document.write或依赖全局变量顺序，极易出错 - 开发时用
file://协议打开 HTML，跨域限制会导致import()失败且无详细错误，务必加crossorigin="anonymous"
真正难的不是怎么写 import()，而是判断哪些节点该升级、何时升级、是否要重试、以及 SSR 和 CSR 渲染一致性怎么保——这些都得在业务层兜底，浏览器不帮你管。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
