Vue 2+Vite项目如何兼容lit-element构建的第三方Web Components？

问题成因 #

两个报错均由Vite与Webpack的默认资源处理逻辑差异导致，和组件本身无关：

• Vue抛出的未知自定义元素错误：Vue2默认将所有未在组件内注册、未全局注册的标签判定为未注册Vue组件，不会自动识别通过customElements.define注册的原生Web Components。
• lit-element抛出的adoptedStyleSheets赋值错误：原Webpack构建流程中，lit-scss-loader会将lit组件内引入的CSS/SCSS文件预编译为CSSStyleSheet实例，符合ShadowRoot对adoptedStyleSheets的入参要求；Vite默认没有对应处理逻辑，会将样式文件处理为普通字符串或资源URL，传入时类型不匹配直接触发异常。

修复步骤 #

1. 修复Vue未知自定义元素报错 #

在Vite的Vue2插件配置中，声明用到的lit组件标签为原生自定义元素，跳过Vue组件解析逻辑。
配置示例（vite.config.js）：

import { createVuePlugin } from 'vite-plugin-vue2'

export default {
  plugins: [
    createVuePlugin({
      compilerOptions: {
        // 按实际使用的组件前缀配置，精确匹配可减少不必要的解析
        isCustomElement: tag => tag.startsWith('foo-')
        // 全量匹配所有自定义元素可写为：isCustomElement: tag => tag.includes('-')
      }
    })
  ]
}

2. 修复adoptedStyleSheets类型错误 #

需要对齐原Webpack下lit-scss-loader的样式处理能力，优先选择插件方案，兼容性更好。

推荐方案：使用Vite生态的lit样式处理插件

安装对应插件，将lit组件引入的样式文件预编译为CSSStyleSheet实例：

npm install vite-plugin-lit-css -D

修改Vite配置，注意必须将第三方lit组件所在的node_modules路径加入插件处理范围（插件默认忽略node_modules下的文件）：

import { createVuePlugin } from 'vite-plugin-vue2'
import litCss from 'vite-plugin-lit-css'

export default {
  plugins: [
    createVuePlugin({
      compilerOptions: {
        isCustomElement: tag => tag.startsWith('foo-')
      }
    }),
    litCss({
      include: [
        /\.(css|scss|less)$/,
        // 替换为实际引入的第三方lit组件包名
        /node_modules\/@your-scope\/foo-component-package/
      ]
    })
  ],
  optimizeDeps: {
    // 强制预构建第三方lit包，避免ESM/CJS兼容问题
    include: ['@your-scope/foo-component-package']
  }
}

配置完成后重启Vite开发服务、清除依赖缓存即可正常运行。

临时兼容方案（仅适合组件数量极少的场景）

如果不想引入额外插件，可在项目入口文件最顶部添加全局补丁，自动将传入的非CSSStyleSheet类型样式转换为合法实例：

// main.js 最顶部添加
if (!window.__litCompatPatched) {
  const desc = Object.getOwnPropertyDescriptor(ShadowRoot.prototype, 'adoptedStyleSheets')
  Object.defineProperty(ShadowRoot.prototype, 'adoptedStyleSheets', {
    configurable: true,
    enumerable: true,
    get() {
      return desc.get.call(this)
    },
    set(val) {
      const processed = val.map(item => {
        if (item instanceof CSSStyleSheet) return item
        if (typeof item === 'string') {
          const sheet = new CSSStyleSheet()
          sheet.replaceSync(item)
          return sheet
        }
        return item
      })
      return desc.set.call(this, processed)
    }
  })
  window.__litCompatPatched = true
}

注意：该补丁为全局侵入式修改，若项目中有其他操作ShadowRoot的逻辑可能存在冲突，优先使用插件方案。

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