使用unpkg CDN加载Lit 3.0 my-element组件无法渲染的问题排查

问题背景 #

在Lit 2.0中，Web组件发布至npm后可通过以下script标签直接引入使用：

<script src="https://unpkg.com/@fireflysemantics/fs-gist"></script>

该组件的package.json关键配置如下：

"main": "fs-gist.bundle.js",
"module": "fs-gist.js",
"types": "fs-gist.d.ts",
"type": "module",

基于Lit 3.0 TypeScript启动模板的my-element示例复用此流程，已将测试组件发布为npm包@fireflysemantics/wctest，其package.json关键配置为：

"main": "my-element.bundled.js",
"module": "my-element.js",
"types": "my-element.d.ts",
"type": "module",

但通过unpkg CDN引入rollup构建包后组件无法渲染，以下是具体排查思路：

排查步骤 #

• 确认unpkg资源指向正确性
  直接访问组件的unpkg地址（如https://unpkg.com/@fireflysemantics/wctest），验证跳转后的资源是否为my-element.bundled.js且内容完整。若unpkg未正确加载目标bundle，可在package.json中添加unpkg字段明确指定CDN入口文件：

  "unpkg": "my-element.bundled.js"
  

• 检查bundle的依赖兼容性
  Lit 3.0与2.0存在依赖版本差异，查看浏览器控制台是否有Lit is not defined类错误：

  • 若bundle依赖外部Lit，需确保页面先引入Lit的CDN资源，再加载组件bundle；
  • 若为全量打包，确认rollup配置已将Lit正确打包进bundle，避免依赖缺失。

• 验证组件注册逻辑
  检查my-element.bundled.js中是否包含自定义元素注册代码：

  customElements.define('my-element', MyElement);
  

  若rollup打包时移除了注册逻辑，或模板代码未自动注册组件，浏览器将无法识别该元素。

• 排查浏览器控制台报错
  打开测试页面开发者工具：

  • 在Network标签确认组件bundle是否成功加载（HTTP状态码为200）；
  • 在Console标签查看是否存在语法错误、依赖错误或自定义元素注册失败的提示。

• 适配Lit 3.0的构建配置
  检查rollup配置是否适配Lit 3.0特性：

  • 确认输出格式为iife或umd（适合CDN直接引入），而非仅es模块；
  • 确保转译配置正确处理装饰器、类字段等语法，避免浏览器无法识别的特性。

• 测试本地bundle可用性
  将本地构建的my-element.bundled.js直接放入测试页面目录，通过本地路径引入验证是否能正常渲染。若本地正常但CDN失效，需检查npm发布的文件列表（确认package.json的files字段是否包含bundle文件）。

内容的提问来源于stack exchange，提问作者Ole